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!
Top comments (0)