Documentação que as pessoas realmente leem
Quatro documentos que bastam
Um arquivo de início. O que é, como rodar localmente, como rodar os testes e quem perguntar. Precisa ser preciso — é o documento verificado em todo onboarding.
Decisões de arquitetura. Uma página por decisão significativa: contexto, opções, o que foi escolhido e por quê. Curto e datado.
Operações. O que fazer quando algo quebra, como fazer deploy, como fazer rollback.
Interface. A partir do próprio código, para que não envelheça.
Como manter fresco
Documentação que vive perto do código e é atualizada na mesma pull request. Um documento em outro lugar envelhece em dois meses, e pior — continua parecendo autoritativo.
O que não documentar
O que o código diz claramente. Um comentário que descreve uma linha é redundante; um comentário que explica por que uma abordagem incomum foi escolhida vale ouro.
Indo mais fundo
Verifique o arquivo de início em todo onboarding: faça um recém-chegado segui-lo ao pé da letra e anote cada lugar em que travou. É a única forma de encontrar as suposições silenciosas que todos os veteranos guardam na cabeça e ninguém escreveu.