sergio-balecho Docs
Documentação técnica com tipo certo para cada pergunta. A maior parte da documentação ruim não é mal escrita: é do tipo errado. Quem quer resolver um problema agora não quer ler conceito; quem quer entender a decisão não quer passos. Antes de escrever, classifique; antes de revisar, confira se cada parte está no tipo certo.
Os quatro tipos (Diátaxis)
Pergunta que o leitor traz → tipo do documento:
- Tutorial — "me ensine a dar os primeiros passos". Aprendizado guiado, resultado garantido. O autor já testou cada comando na ordem, num ambiente limpo; nada de "deixe como exercício".
- How-to (guia) — "como faço X?". Passos para quem já sabe o básico e tem um objetivo próprio. Direto ao ponto, um how-to por objetivo, sem teoria no meio.
- Referência — "o que exatamente faz essa função/opção/flag?". Descrição seca e completa, consultada durante o trabalho. Organização por estrutura do código (cada endpoint, cada parâmetro), não por dificuldade. Nenhuma opinião.
- Explicação (conceito) — "por que é assim?". Contexto, decisão, alternativa descartada. Pode discutir, pode opinar, não manda o leitor executar nada.
Um documento tem um tipo dominante. Trecho do outro tipo vira link para o documento dele. Antes de escolher estrutura, decida o tipo e escreva no topo (para si) que pergunta este documento responde.
README
O README responde em 30 segundos: o que é, para quem, por que existe, como rodar. Nesta ordem: nome e uma frase do que é; badge de estado se houver; pré-requisitos; instalação e execução mínima (comando a comando, testados); exemplos mínimos de uso; onde vai a documentação mais profunda (links); como contribuir ou onde estão as regras; licença. O README não é documentação completa — é a porta. Regra de corte: cada seção deve sobreviver à pergunta "um leitor novo desistiria se esta seção não existisse?".
Referência de API
Para cada endpoint/operação, o mesmo molde, sempre completo — leitor pula o que não precisa, mas nunca descobre pela falta que precisava: o que faz em uma frase; método e caminho; autenticação exigida; cada parâmetro com tipo, obrigatório ou não, default e restrição; corpo de request com exemplo; cada resposta possível com código, significado e exemplo de corpo — inclusive erros; idempotência, limites de taxa e efeitos colaterais. Exemplos copiáveis e consistentes entre si (o mesmo objeto nos dois lados). Não descreva código interno; descreva o contrato.
ADR (Architecture Decision Record)
Um ADR por decisão relevante e irreversível ou cara de reverter. Molde curto (Nygard): número e título no imperativo ("ADR-007: adotar Postgres com row-level locking"); Status (proposto, aceito, substituído pelo ADR-n); Contexto (o problema e as forças em jogo, fatos, não narrativa); Decisão (o que decidimos, uma frase clara); Consequências (o que fica mais fácil, o que fica mais difícil, o que assumimos). Alternativas consideradas entram no Contexto com o motivo de cada descarte, em uma linha cada. ADR não se edita para mudar de opinião: novo ADR marca o antigo como substituído. Uma decisão, um arquivo, imutável.
Changelog
Siga Keep a Changelog: arquivo CHANGELOG.md, seções por versão com data (formato ISO), categorias Novidades / Mudanças / Correções / Removido; a versão seguinte fica em "Não lançado" até sair. Cada entrada orientada a quem usa o software: "Corrigido o crash ao abrir anexo acima de 10 MB", não "fix null check". Mudança que quebra (breaking change) está destacada e diz o que o usuário precisa fazer.
Estilo
- Frases curtas, voz ativa, presente. "O serviço valida o token" vence "o token é validado pelo serviço".
- Segunda pessoa no how-to e no tutorial ("você cria a migração"); impessoal na referência.
- Termo sempre igual para a mesma coisa: escolha "iniciar sessão" ou "abrir sessão", nunca os dois. Se o código chama de
worker, o texto chama de worker (com tradução na primeira ocorrência se precisar). - Todo bloco de código roda: comando completo, caminho real, sem "..." no meio do que importa.
- Figura só se elimina texto; screenshot com seta expira — prefira texto ou diagrama estável.
- Escreva para o leitor que chega hoje: sem "como sabem", sem referência a discussão que não está linkada.
Verificação
Percorra references/checklist-revisao.md em todo documento antes de entregar. O teste final: dê o documento a alguém que não participou (ou releja fingindo ser esse leitor) e pergunte qual pergunta ele responde. Se a resposta não é a pergunta do tipo escolhido, o documento está no tipo errado.
Recuse
- Documento que mistura os quatro tipos sem separação: proponha a divisão antes de escrever.
- Documentação de API escrita de cabeça, sem ler o código: a referência descreve o contrato real, não o desejado.
- ADR para decidir coisa trivial: decisão reversível e sem custo não merece registro.
- Documentar feature inexistente ou futura como se existisse; documento de roadmap fica no roadmap.