Escreva no dia em que deu errado, não no dia em que sobrar tempo

Todo mundo concorda que deveria documentar. E quase todo mundo agenda isso pra um bloco futuro: uma tarde, uma semana calma, o mês que vem.

Quando a tarde chega, você escreve de memória. E de memória sai o que qualquer um escreveria: passo genérico, ordem óbvia, nenhum detalhe que importa.

O detalhe some rápido

O que salva quem lê não é a sequência de passos. É a armadilha: o campo que precisa ser preenchido antes do outro, o erro que aparece sem explicação, o lugar onde a interface mente.

Isso você sabe no dia em que perdeu duas horas descobrindo. Uma semana depois, lembra que “teve um problema” e não lembra qual.

O gatilho certo

Documentar não é tarefa de agenda, é reação a evento. Três eventos valem:

Deu errado e você descobriu por quê. Escreva a causa e o sinal que a denuncia, não só a solução.

Alguém te perguntou a mesma coisa pela segunda vez. A segunda vez é o sinal. A primeira pode ser acaso.

Você fez algo que só você sabe fazer. Se some você, some a capacidade.

O formato mínimo que funciona

Três linhas resolvem a maior parte dos casos: o que aconteceu, como saber que é isso, o que fazer. Nessa ordem.

O “como saber que é isso” é a parte que quase todo mundo pula e é a que faz o documento ser útil. Sem ela, quem lê precisa já ter diagnosticado pra encontrar o texto certo.

Onde guardar

No lugar mais próximo de onde o problema aparece, não numa pasta de documentação que ninguém abre. Se o erro acontece num script, o comentário fica no script. Se acontece num processo, fica no checklist do processo.

Documento longe do uso envelhece sem ninguém notar, e documento errado é pior que documento nenhum, porque tem autoridade.