Por que documentação técnica existe e por que ninguém quer fazer
Ao longo do tempo os seres humanos reconheceram a importância de documentar sistemas, decisões de arquitetura e fluxos de operação, mas o reconhecimento veio tardio na maioria dos projetos. Eu já vi equipe inteira passar três meses reconstruindo lógica de negócio que só existia na cabeça de uma pessoa que saiu em fevereiro. Não foi drama, foi apenas a consequência natural de tratar documento como tarefa secundária. O problema não é a falta de ferramentas. Qualquer um consegue criar uma pasta no Confluence ou abrir um arquivo Markdown num repositório Git. O problema é o que fazer com esse espaço vazio depois de criado.O que costuma funcionar na prática
Eu comecei a adotar um fluxo bem simples há uns anos e ele tem sustentado projetos de médio a grande porte sem colapsar. A base é escrever três coisas de forma consistente: o que o sistema faz, o que ele não faz, e por quê. O último item é o mais negligenciado e também o mais caro de recuperar depois. A decisão de usar X em vez de Y precisa ficar registrada. Não a opinião de alguém num comentário de PR. Um documento de decisão de arquitetura, um ADRE ou algo similar, com data, contexto, alternativas consideradas e o critério de escolha. Quando eu entro num projeto legado e preciso justificar uma escolha feita há dois anos, não quero depender da memória de ninguém.Decisions.md no root do repositório funciona. Não precisa de estrutura complicada. Título, data, estado (ativo, descontinuado, supersedido), alternativas avaliadas, decisão tomada e rationale. Se o formato parecer ridículo num primeiro olhar, é porque você ainda não passou por uma migração problemática.
ao longo do tempo os seres humanos reconheceram a importância de documentar para não repetir erros
O ponto que as pessoas costumam perder é que documentação não serve para o futuro distante. Serve para o futuro imediato, quando você ou outro desenvolvedor precisa tomar uma decisão parecida e não quer gastar duas semanas descobrindo o mesmo calcanhar de Aquiles que já foi identificado. Uma coisa que eu aprendi na prática e que não está em nenhum guia: a documentação técnica sobrevive tanto quanto o processo de manutenção dela. Se ninguém atualiza, ela vira ruído. Eu vi times inteiros abandonarem Confluence porque o conteúdo virou espelho do passado, não do presente. O sistema mudou em novembro, o documento foi atualizado em março do ano anterior, e todo mundo passou a confiar na versão desatualizada por preguiça de verificar. O workaround que eu encontrei foi simples e nada elegante. Colocar um campo "última atualização" e "próxima revisão" em cada documento. Se a data de revisão passou e ninguém marcou como revisado, o sistema de CI gera um alerta no canal da equipe. Não é perfeito, mas reduziu a quantidade de informação obsoleta circulando pelo escritório digital.Outro detalhe prático: documentação técnica deve seguir o mesmo processo de code review. Não é opcional. Um pull request que altera comportamento de sistema sem atualizar a docs correspondente deve ser barrado. Eu já deixei PRsem dois dias porque o código estava certo e a documentação estava errada. Ninguém notou porque quem faz review foca no diff do código.
👉 Clique no botão abaixo para saber mais sobre o assunto!
O que documentar de fato
Não precisa ser tudo. A tentação é documentar cada função, cada parâmetro, cada endpoint. Isso gera volume que ninguém lê. O que vale a pena documentar é o que não é óbvio a partir do código. Se o código já diz o que faz, não repita isso em texto. Escreva sobre as escolhas, as restrições, os pontos de falha conhecidos e os workarounds que ninguém conta nas reuniões.Um exemplo concreto que eu tive: um serviço de processamento de filas que falhava intermitentemente em horários de pico. O código não mostrava nada de errado. O log parecia normal. A causa raiz era um limite de conexão do banco de dados que só era atingido em cenários específicos de. A documentação que resolvia isso era uma página de Runbook com os passos exatos de recuperação e um grafano link para monitorar o campo em tempo real. Levamos uma semana inteira para escrever aquilo. Foi uma semana bem gasto, mas desde então aquele incidente leva cinco minutos para resolver.
Isso me leva a outro ponto que parece contraditório mas é verdade: menos documentação às vezes é mais útil do que mais. Um único documento bem escrito sobre o sistema completo vale mais do que cinquenta páginas fragmentadas que se contradizem. A prioridade deve ser consistência, não quantidade.Ferramentas que não atrapalham
Markdown, repositório Git, e algum sistema de busca integrado. Isso é o suficiente. O problema raramente é a ferramenta. O problema é a cultura de não escrever. Eu já vi times migrarem de Wiki para Notion para Obsidian e voltar para Docs do Google porque ninguém se adaptava ao novo fluxo. Cada migração custa tempo produtivo que poderia ter sido usado para escrever conteúdo útil. A ferramenta que everyone já sabe usar é melhor do que a ferramenta perfeita que ninguém usa.Se o time já usa Git, fica no repositório junto com o código. Se o projeto é grande e tem múltiplos subsistemas, uma estrutura de pastas por domínio com arquivos README.md em cada nível funciona razoavelmente bem. Não precisa de diagrama complexo. Só precisa de organização que permita encontrar a informação em menos de trinta segundos.
Quando a documentação falha de vez
Existem cenários onde documentação escrita simplesmente não funciona. Sistemas extremamente dinâmicos, onde a lógica muda semanalmente, ou equipes muito pequenas onde a comunicação oral substitui qualquer registro. Nesses casos, forçar documentação gera trabalho morto. O que eu faço nesses casos é registrar apenas os pontos de decisão críticos e os riscos conhecidos. O resto fica como conhecimento tácito que é transferido via pair programming ou sessões de onboarding estruturadas. Às vezes a melhor documentação é uma pessoa explicando para outra.Também existe o caso oposto: times que documentam tudo e confiam cegamente no documento. Isso é perigoso porque cria uma falsa sensação de segurança. O documento diz que o sistema comporta X, mas na produção ele comporta X mais Y que ninguém anotou. Sempre verifique a realidade contra o documento, nunca o contrário.
