Por Que a Documentação Que Você Passou 2 Semanas Escrevendo Ninguém Lê

Você senta, dedica duas semanas pra documentar tudo direitinho. 40 páginas, bem formatado, com diagramas. Manda pro time.

Uma semana depois, alguém pergunta algo que está bem lá na página 23 da documentação. E quando você aponta, a resposta é: "Ah, desculpa, não li."

Aí você se pergunta: por que as pessoas não leem a documentação que eu fiz?

A resposta é simples: porque você documentou pra você, não pra eles.

O padrão dos documentos que ninguém lê:

Muita prosa. "A integração com o sistema legado, que é um sistema que funciona assim, foi desenvolvido em 2008, e ele tem certas particularidades..." — ninguém aguenta. Você só quer saber: como funciona, pronto.

Sem estrutura clara. Tudo em um texto corrido. O cara não consegue encontrar o que precisa.

Muito detalhe em lugar errado. Está escrito como funciona a integração em 5 páginas, mas não está claro por que existe uma integração assim.

Fora do contexto de quem vai usar. Você documentou de um jeito que faz sentido pra você, mas quem vai usar pra trabalhar tem uma perspectiva diferente.

Sem hierarquia. Tudo é importante, então nada é importante. O cara não sabe por onde começar.

Por que documentação importa (mesmo que ninguém leia):

Porque quando aquele cara que sabe tudo sai da empresa, é a documentação que fica.

Porque novo membro do time não pode ficar perguntando pro seu colega como funciona tudo.

Porque decisões documentadas não viram discussão depois.

Porque quando você sai do projeto por seis meses e volta, você não lembra de nada sem a documentação.

Como documentar pra verdade:

Pense em quem vai ler. É novo no time? É do cliente? É da liderança? Documenta diferente pra cada um.