DEV Community

Cover image for Como escrever boas documentações na empresa
Vinicius Blazius Goulart for Highsoft Sistemas

Posted on • Updated on

Como escrever boas documentações na empresa

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

Descrição da imagem
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:

Image description

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!

Oldest comments (0)