Documentação como produto — o que aprendi numa empresa onde escrever é trabalhar
Em times distribuídos de alta performance, documentação não é overhead — é o principal mecanismo de escala. Aqui está como pensar sobre isso de forma diferente.
Eu costumava achar que documentação era o que você escrevia depois de terminar o trabalho real. Uma obrigação, não parte do trabalho. Algo para marcar no checklist antes de fechar o ticket.
Trabalhar num time onde documentação é tratada com o mesmo rigor que código mudou isso completamente.
O insight central: documentação não é registro do passado — é infraestrutura para o futuro. Quando você escreve documentação de qualidade sobre uma decisão, você não está explicando o que já aconteceu. Você está criando capacidade para que outras pessoas tomem decisões similares de forma autônoma no futuro.
Cada hora bem gasta em documentação multiplica por N — N sendo o número de pessoas que eventualmente vão precisar dessa informação.
Documentação de decisão é diferente de documentação de implementação. Implementação descreve o quê: como o sistema funciona, quais são os endpoints, qual é o schema. Decisão descreve o porquê: qual problema estávamos resolvendo, quais alternativas foram consideradas, por que escolhemos esta abordagem, o que seria diferente se soubéssemos então o que sabemos agora.
Documentação de implementação fica obsoleta rapidamente — o sistema muda e a doc fica desatualizada. Documentação de decisão tem vida longa — o contexto de por que algo foi feito de um jeito permanece relevante mesmo quando a implementação muda.
O padrão que funcionou melhor para mim foi documentar no momento em que a decisão é tomada — não depois. Quando você está no meio de avaliar alternativas, o contexto está vivo na sua cabeça. Uma semana depois, o raciocínio já está parcialmente perdido. Três meses depois, você não consegue reconstruir por que a alternativa B foi descartada.
Escrever no momento não é overhead — é capturar contexto que vai desaparecer de qualquer forma. A questão é se vai desaparecer da memória coletiva do time ou vai ficar preservado onde alguém pode encontrar.
Uma coisa que mudou na forma como escrevo: penso no leitor antes de escrever. Quem vai ler isso? O que eles já sabem? O que eles precisam saber que não está no texto? Quando é documentação técnica para o time, assumo familiaridade com o domínio mas não com os detalhes específicos do sistema. Quando é documentação de onboarding, assumo zero contexto.
Documentação genérica — escrita sem leitor específico em mente — tende a ser igualmente inútil para todos.
O que não funciona: documentação que tenta ser completa. A busca pela documentação completa leva à documentação que ninguém mantém porque é muito trabalhoso manter tudo atualizado. O melhor é documentação focada: cobre o que é mais provável de ser perguntado, é honesta quando há gaps, e tem um responsável claro por mantê-la atualizada.
Documentação com responsável envelhece melhor do que documentação de ninguém.
Há uma habilidade específica que desenvolvi que não esperava: escrever assincronamente de forma que elimina necessidade de reunião. Quando você aprende a escrever propostas, análises e atualizações de status de forma suficientemente clara e completa, percebe que muitas reuniões que você marcaria para "alinhar" se tornam desnecessárias. O documento alinha. A reunião existe para perguntas que o documento não respondeu — que é um uso muito mais eficiente do tempo de todos.
O teste que uso para saber se a documentação está boa: imagino alguém no time que eu não conheço bem, em fuso diferente, precisando usar essa informação sem poder me perguntar nada. Eles conseguiriam chegar à conclusão ou ação correta? Se não, o documento não está pronto.
Essa semana: pega um processo no seu trabalho que você já explicou para pelo menos três pessoas diferentes. Escreve o documento que teria poupado essas três conversas. Compartilha com alguém que não conhece o processo e pede que tente seguir sem te perguntar nada. O que eles ficaram presos revela o que falta no documento.