Você já abriu o README de um projeto, leu tudo e continuou sem saber como rodar a coisa? Pois é. O problema quase nunca é falta de documentação. É documentação em que ninguém confia.
O problema não é falta de doc, é doc que ninguém confia
Todo time tem uma pasta docs/ cheia. Ninguém lê. Porque na primeira vez que alguém seguiu um passo a passo e ele estava errado, a doc virou ficção. A partir daí todo mundo pula direto pro código ou pergunta no chat.
Doc boa não é doc grande. É doc que você lê e confia. Todo o resto deste texto é sobre como ganhar essa confiança.
O README responde as 5 primeiras perguntas
Quem abre seu repo chega com cinco perguntas, quase sempre nessa ordem:
- O que é isso?
- Como rodo localmente?
- Como rodo os testes?
- Como contribuo?
- Onde peço ajuda quando travar?
Se o README responde essas cinco em trinta segundos de leitura, ele fez o trabalho. O resto é bônus. E cuidado: tudo que você coloca antes dessas respostas — badge bonito, história do projeto, diagrama de arquitetura — vira obstáculo entre a pessoa e o que ela precisa. Enterre isso mais pra baixo.
Explique o porquê, não só o como
O como o código já conta. retry(3) é óbvio para qualquer um que lê a linha. O que ninguém adivinha é por que três, e não cinco. Ou por que existe retry, afinal.
Doc que só descreve o que o código faz é redundante e envelhece rápido: mudou o código, a doc mentiu. Doc que explica a decisão sobrevive à refatoração. Então registre o motivo, o trade-off, aquela abordagem que você tentou e abandonou. Isso o git blame não te entrega às duas da manhã.
Doc longe do código é doc morta
Doc que mora num Confluence esquecido morre no dia seguinte ao deploy. Ninguém atualiza o que não vê no fluxo normal de trabalho.
Aproxime a explicação do que ela descreve:
- README na raiz de cada módulo, não só na do repo
- comentário em cima da função esquisita, explicando a esquisitice
- um ADR curto (uma decisão, meia página) na própria pasta do projeto
Quanto menor a distância entre o código e a explicação, maior a chance de a explicação continuar verdadeira quando o código mudar — porque ela está ali, no mesmo diff, pedindo pra ser atualizada.
Exemplo vale mais que três parágrafos
Ninguém lê a descrição textual de um parâmetro. Todo mundo procura o exemplo, copia e adapta. Um bloco de código que roda ensina mais rápido que qualquer prosa caprichada.
Melhor ainda: exemplo que é testado. Se o snippet do README roda no CI — nem que seja um teste bobo que só executa o exemplo — ele nunca mente por muito tempo. Doc que quebra o build quando fica desatualizada é doc que se mantém quase sozinha. É o truque mais barato pra evitar rot.
Doc que mente é pior que doc que falta
Doc que falta é honesta: você sabe que vai ter que perguntar ou ler o código. Doc que mente custa uma hora seguindo um caminho que não existe mais — e ainda mata a confiança em todo o resto do que está escrito.
Então trate doc como código:
- apagou uma feature, apague a doc dela no mesmo PR
- mudou o passo, mude o texto agora, não "depois"
- não vai manter? delete
Um README de três linhas verdadeiras vale mais que trinta linhas de mentira. Escreva menos, mas escreva o que é verdade hoje. Documentação não morre por ser curta — morre por ser falsa.
