Acompanhe esse post no nosso Dev.to!
Estou criando este post baseado no The documentation system, mas por ele ser um artigo longo resolvi fazer um resumo dele com mais algumas coisas. Mas recomendo que você leia e estude este artigo, ele possui mais conteúdo e casos específicos com explicação e contexto para eles.
Tópicos
Uma boa documentação deve ter 4 tópicos principais:
- Explicação: explicação discursiva
- Referência: descrição seca
- Tutorial: uma lição
- Como fazer: uma série de passos
créditos: The documentation system
Como fazemos na Highsoft?
Depois de escolher um tópico para escrever e documentar, a primeira coisa a fazer é a referência e a explicação. Primeiro deve-se fazer uma explicação literal do termo, e depois explicar como tal tópico funciona em nosso sistema.
Para criar o tutorial, pegamos o tópico em questão e explicamos o procedimento de ponta a ponta, de forma simples, rápida, básica e útil.
Devemos complementar então com o como fazer, onde tratamos de assuntos mais específicos e nos aprofundamos nas explicações
Adicionamos mais um tópico para possíveis avisos e a explicação deles. Como somos um ERP, é normal dispararmos avisos nas telas para informar o que está acontecendo, e temos um tópico para descrever esses avisos e apontar possíveis problemas que podem ocorrer.
Por final, temos isso:
Lembre-se de sempre se colocar no lugar do cliente e tentar entender as possíveis respostas que ele precisa:
- como fazer isso?
- O que é isso?
- o que eu faço quando...?
- por quê isso aconteceu?
Se sua documentação tem a resposta para essas perguntas, você tem uma boa documentação. Se não, basta adicioná-lo!