Como escrever boa documentacao

Porque documentar?

Documentacao clara reduz o tempo que novos colaboradores precisam para se tornarem produtivos e evita que conhecimento critico se perca quando alguem sai da equipa.

Principios fundamentais

1. Escreve para quem nao sabe

Nunca assumas que o leitor tem o teu contexto. Explica os “porques” alem dos “comos”. Um passo que te parece obvio pode bloquear alguem durante horas.

2. Comeca pelo resultado

A primeira frase de cada pagina deve dizer o que o leitor vai conseguir fazer depois de a ler. Ninguem quer ler tres paragrafos antes de saber se esta na pagina certa.

3. Usa exemplos concretos

Um bom exemplo vale mais que dez paragrafos de explicacao abstracta. Mostra comandos reais, valores reais, resultados reais.

4. Mantem actualizada

Documentacao desactualizada e pior do que nenhuma — cria falsa confianca. Quando mudas o codigo, actualiza a documentacao no mesmo momento.

5. Uma pagina, um tema

Cada documento deve cobrir um unico tema ou tarefa. Se precisas de fazer scroll durante muito tempo, provavelmente devias dividir em paginas separadas.

Estrutura recomendada

• Titulo claro — descreve o que a pagina cobre
• Introducao curta — uma ou duas frases sobre o objectivo
• Pre-requisitos — o que o leitor precisa ter antes de comecar
• Passos ou explicacao — o conteudo principal, com sub-titulos
• Exemplos — blocos de codigo, screenshots, ou diagramas

Erros comuns a evitar

• Documentar tudo de uma vez em vez de documentar enquanto trabalhas
• Usar jargao interno sem o definir
• Copiar codigo sem explicar o que faz
• Escrever documentacao que so tu consegues entender
• Nunca rever o que escreveste — le em voz alta, melhora muito

Ferramentas uteis

• Markdown — formato simples, legivel, e universal
• Screenshots com anotacoes — para interfaces visuais
• Diagramas — para arquitectura e fluxos (Mermaid, draw.io)
• Exemplos executaveis — comandos que o leitor pode copiar e correr