Documentação que a equipe realmente usa: o que escrever, o que jogar fora

Todo time tem uma pasta de documentação que ninguém abre. Ela existe porque em algum momento alguém decidiu, com boa intenção, que "precisamos documentar isso melhor". Nasceu um wiki, um Confluence, um Notion, uma pasta docs/ no repositório. Nos primeiros meses, algumas páginas foram escritas com carinho. Depois o produto mudou, a arquitetura evoluiu, três pessoas saíram, duas entraram, e aquele material foi ficando para trás sem que ninguém percebesse. Hoje, quando um dev novo pergunta onde estão os docs, a resposta vem com uma ressalva embutida: "tem, mas não confia muito, pergunta pra alguém".

Essa cena é tão comum que virou piada interna em quase toda equipe de software. E a conclusão errada que muitos tiram dela é que documentação não vale o esforço — que código bom se documenta sozinho e que o resto é burocracia. A conclusão certa é outra: a maioria da documentação apodrece porque foi escrita sem entender o que documentação é para servir, onde ela deve morar e quem vai mantê-la viva. Documentação que a equipe realmente usa não é um volume maior de texto; é um conjunto menor de peças certas, no lugar certo, atualizadas pelo mesmo fluxo que muda o código. Este artigo é sobre como chegar lá — de forma prática e independente de ferramenta.

Por que a documentação apodrece#

Antes de falar do que escrever, vale entender por que o que já foi escrito estragou. Porque se você não muda a causa, vai só produzir mais material para apodrecer no mesmo ritmo.

A primeira causa é a distância. A documentação típica mora longe do código que ela descreve. O código está no repositório; a doc está num wiki que abre em outra aba, atrás de outro login, indexado por outra busca. Essa separação física parece um detalhe, mas é a raiz do problema. Quando você altera uma função, o arquivo de código está ali, na sua frente, no diff. A página do wiki que descreve o comportamento dessa função está a três cliques e uma troca de contexto de distância — e, na prática, você nunca vai até lá. A doc não é atualizada não porque as pessoas são preguiçosas, mas porque o custo de lembrar que ela existe, encontrá-la e editá-la é alto o suficiente para perder toda vez para o próximo item do backlog.

A segunda causa é que ninguém é dono. Documentação costuma ser responsabilidade difusa: é de todos e, portanto, de ninguém. Não entra na definição de pronto, não aparece na revisão de código, não trava merge nenhum. Um teste que quebra bloqueia o deploy; uma doc desatualizada não bloqueia nada. Sem um mecanismo que force a atualização a acontecer junto com a mudança, a entropia vence. A doc não decai porque alguém decidiu abandoná-la — ela decai por omissão, um commit por vez, cada um individualmente justificável.

A terceira causa é que ela foi escrita para o momento errado. Muita documentação registra o estado do mundo num dia específico — a captura de tela da interface que já mudou, a lista de endpoints que já cresceu, o passo a passo de instalação que assume uma versão de dependência que já foi atualizada. Esse tipo de conteúdo nasce com prazo de validade curto porque acompanha os detalhes mais voláteis do sistema. Quanto mais preso ao "o quê" mecânico e efêmero, mais rápido o texto vira arqueologia: um registro de como as coisas eram, não de como são.

O resultado combinado é previsível. A documentação acumula afirmações que já não são verdade, ninguém tem incentivo para corrigi-las, e a equipe aprende, por experiência, a não confiar em nada que esteja escrito. A partir daí a doc não só não ajuda — ela ativamente atrapalha, porque toda consulta precisa ser verificada contra a realidade do código, o que é mais lento do que simplesmente ler o código desde o começo.

Nem toda doc é a mesma coisa#

Boa parte do fracasso vem de tratar "documentação" como uma coisa só. Não é. Um leitor que está aprendendo a usar o sistema pela primeira vez tem uma necessidade completamente diferente de um leitor experiente que só quer lembrar a assinatura de um comando. Misturar essas necessidades no mesmo documento produz um texto que não serve bem para nenhuma delas. Existem quatro tipos distintos de documentação, e cada um responde a uma pergunta diferente.

O tutorial ensina alguém a começar. Ele é orientado a aprendizado, feito para quem ainda não conhece o sistema. Um bom tutorial pega o leitor pela mão e o leva do zero até um primeiro resultado concreto e funcionando, sem desvios. Ele é deliberadamente opinativo: escolhe um caminho e não oferece alternativas, não explica cada decisão, não lista todas as opções possíveis. O objetivo é a sensação de "funcionou, eu consegui" no menor tempo possível, porque é isso que dá confiança para o iniciante continuar. Um tutorial que para no meio para discutir trade-offs de configuração falhou no seu único trabalho. O erro clássico é encher o tutorial de ressalvas e completude — é aí que ele deixa de ensinar.

O guia how-to resolve um problema específico. Ele é orientado a tarefa e assume que o leitor já sabe o básico. É a receita: "como configurar autenticação com OAuth", "como fazer o deploy para staging", "como migrar o banco sem downtime". Diferente do tutorial, o how-to não ensina do zero — ele parte de um objetivo concreto que o leitor já tem em mente e mostra a sequência de passos para alcançá-lo. Um bom guia how-to é focado: resolve um problema real, não uma categoria abstrata de problemas, e não tenta explicar toda a teoria por trás. É o tipo de documento que alguém abre no meio do trabalho, com um objetivo claro e pressa para voltar a ele.

A referência descreve o que existe. É orientada a informação e feita para consulta, não para leitura contínua. É a lista de endpoints da API com seus parâmetros, a tabela de variáveis de ambiente, a assinatura de cada função pública, os códigos de erro possíveis. A referência é seca por natureza — precisa ser precisa, completa e consistente, não envolvente. Ninguém lê referência da primeira à última linha; as pessoas pulam direto para a entrada que precisam. Por isso a referência deve espelhar fielmente a estrutura do que descreve e evitar narrativa. É também o tipo de documentação que mais se beneficia de ser gerada a partir do próprio código — de anotações, de schemas, de tipos — justamente porque é a que mais rápido diverge quando mantida à mão.

A explicação ilumina o entendimento. É orientada a compreensão, feita para quem quer entender o porquê das coisas. Discute o contexto, as alternativas que foram consideradas, os trade-offs, a história de como a arquitetura chegou onde chegou. A explicação é o tipo de documento que se lê longe do teclado, para formar um modelo mental do sistema. Ela responde perguntas como "por que usamos filas aqui em vez de chamadas diretas?" ou "qual é o modelo de consistência deste serviço?". É o tipo de conteúdo mais difícil de escrever e o mais valioso a longo prazo, porque envelhece bem: os detalhes de implementação mudam, mas as razões por trás das grandes decisões duram.

O ponto prático dessa divisão não é decorar quatro rótulos. É reconhecer, antes de escrever qualquer coisa, qual das quatro perguntas você está respondendo — e não misturar. Quando um documento tenta ser tutorial e referência ao mesmo tempo, ele afoga o iniciante em detalhes e ainda obriga o experiente a garimpar. Quando uma explicação vira how-to no meio, perde o fio da compreensão. Separar por necessidade do leitor é o que faz cada peça ficar utilizável — e, não por acaso, mais fácil de manter, porque cada tipo decai num ritmo diferente e pode ser tratado de forma diferente.

O README que salva o próximo dev#

Se você só puder manter um documento vivo por repositório, que seja o README. Ele é a porta de entrada, o primeiro arquivo que qualquer pessoa abre — humano ou máquina — ao chegar no projeto. E, na maioria dos repositórios, ele é uma decepção: ou está vazio com o nome do projeto e nada mais, ou virou um monstro de vinte seções que ninguém lê. O README que importa é curto e responde às perguntas que o próximo dev realmente tem no primeiro contato.

O README precisa responder rápido a um punhado de perguntas concretas. O que é este projeto, em uma ou duas frases, sem jargão de marketing. Como eu subo isso na minha máquina, do clone até rodar, de verdade e sem passos faltando. Como eu rodo os testes. Como está organizado o código, o suficiente para eu saber por onde começar a procurar. E para onde eu vou se precisar de mais — links para a documentação mais profunda, para o guia de contribuição, para o canal onde as pessoas tiram dúvidas. Um esqueleto útil cabe em pouco espaço:

```markdown # Nome do projeto

Uma ou duas frases dizendo o que é e que problema resolve.

Como rodar localmente#

Pré-requisitos e os comandos exatos, do clone ao "está no ar".

Testes#

Como rodar a suíte e o que é esperado passar.

Estrutura#

As pastas principais e o que vive em cada uma.

Mais#

Links: contribuição, arquitetura, decisões (ADRs), onde pedir ajuda. ```

O maior valor do README é o caminho do zero até rodando. Se um dev novo consegue clonar, seguir a seção de setup e ver o projeto funcionando sem precisar chamar ninguém no chat, o README já pagou seu custo. Essa é também a seção que mais dá para testar: sente-se com quem acabou de entrar, peça para seguir o README ao pé da letra e anote cada ponto em que a pessoa travou. Cada trava é um bug de documentação, tão real quanto um bug de código. Melhor ainda: rode esse caminho num ambiente limpo de vez em quando, porque a máquina de quem escreveu o README já tem metade das dependências instaladas e esconde os passos que faltam.

O que não pertence ao README é tudo que outra peça descreve melhor. Ele não é o lugar da referência completa da API, nem do tutorial passo a passo aprofundado, nem do histórico de decisões. O README aponta para essas coisas, não as contém. Um README que tenta ser tudo vira longo demais para ser lido e, por consequência, longo demais para ser mantido. A disciplina aqui é a mesma do resto: cada tipo de conteúdo no seu lugar, e o README como índice de primeira parada, não como enciclopédia.

Registre a decisão, não só o resultado#

O código conta o "o quê". Ele mostra, com precisão total, o que o sistema faz — basta ler. O que o código não conta é por que ele é assim e não de outro jeito. Por que este serviço usa fila em vez de chamada síncrona. Por que abandonamos aquela biblioteca. Por que existe aquele campo estranho no banco que ninguém ousa remover. Essa informação — o porquê — é a que mais se perde e a mais cara de reconstruir, porque ela nunca esteve escrita em lugar nenhum: morava só na cabeça de quem decidiu, e essa pessoa já saiu do time.

O registro de decisão de arquitetura, o ADR, existe para capturar exatamente isso. É um documento curto, criado no momento em que uma decisão significativa é tomada, que registra quatro coisas: o contexto (qual era a situação e as forças em jogo), a decisão em si, as alternativas que foram consideradas e por que foram descartadas, e as consequências (o que passa a ser verdade, para o bem e para o mal, por causa dessa escolha). Um ADR não precisa ser longo — meia página costuma bastar. O formato é simples de propósito, para não criar atrito na hora de escrever:

```markdown # ADR 007: Fila para notificações em vez de chamada direta

Status#

Aceito

Contexto#

O envio de notificações estava acoplado ao fluxo de checkout. Picos de tráfego derrubavam o checkout junto quando o provedor de e-mail ficava lento.

Decisão#

Publicar as notificações numa fila e processá-las em um worker separado.

Alternativas consideradas#

• Chamada síncrona com retry: mantém o acoplamento, checkout continua refém.
• Cron varrendo a tabela: latência alta e polling desnecessário.

Consequências#

• Checkout não depende mais da latência do provedor.
• Passa a existir entrega eventual: a UI precisa refletir "em processamento".
• Um componente novo (a fila) para operar e monitorar.

```

O valor do ADR aparece meses depois, quando alguém quer mudar aquilo. Sem o registro, a pessoa que encontra a fila hoje não sabe se ela está ali por um bom motivo ou por acidente histórico. Ela pode remover algo que resolvia um problema real que voltará a aparecer — ou pode ficar paralisada, com medo de mexer em código que ninguém entende. Com o ADR, ela lê o contexto original, entende as forças que levaram àquela escolha e decide com informação: ou as forças mudaram e a decisão pode ser revista, ou continuam valendo e a fila fica. O ADR transforma "não mexe nisso, ninguém sabe por quê" em uma decisão que pode ser reavaliada de forma consciente.

ADRs são imutáveis por natureza, e isso é uma vantagem. Você não edita um ADR antigo quando muda de ideia — você escreve um novo que supera o anterior e marca o antigo como substituído. Isso preserva a história do raciocínio: fica claro não só o que se decide hoje, mas a trajetória de como o pensamento do time evoluiu. Diferente de quase toda documentação, o ADR não apodrece, porque ele nunca teve a pretensão de descrever o presente. Ele descreve um momento de decisão, e esse momento não muda. É a raríssima documentação que fica mais valiosa com o tempo, não menos.

Doc que nasce no mesmo PR do código#

Aqui está a mudança que resolve a causa raiz do apodrecimento: a documentação precisa morar perto do código e ser atualizada pelo mesmo ato que muda o código. Tudo o que foi dito sobre distância e falta de dono se dissolve quando a doc vive no repositório e passa pela revisão de código junto com a mudança que a torna necessária.

Doc que mora no repositório está no campo de visão de quem edita o código. Se a documentação de um módulo está num arquivo .md ao lado do módulo, ela aparece na busca do editor, aparece na árvore de arquivos, e — crucialmente — aparece no diff quando alguém mexe naquela área. A pergunta "isso ainda está correto?" acontece naturalmente, porque a doc está fisicamente presente no momento da mudança. Não depende de a pessoa lembrar de um wiki que ela não vê há semanas. A proximidade converte a atualização de um ato de disciplina, que falha, em um ato de conveniência, que acontece.

Tratar doc como código significa submetê-la ao mesmo fluxo. Ela vive no controle de versão, então tem histórico: dá para ver quando cada afirmação foi escrita e junto de qual mudança. Ela entra no mesmo pull request da alteração de comportamento, então a atualização e a mudança são atômicas — não existe uma janela em que o código já mudou mas a doc ainda não. E ela passa pela revisão de código, então um segundo par de olhos verifica se o texto realmente descreve o novo comportamento, do mesmo jeito que verifica a lógica. A doc deixa de ser um passo separado, sempre adiável, e vira parte da unidade de trabalho.

Isso muda o que é "pronto". Uma mudança que altera comportamento observável mas deixa a documentação relevante desatualizada não está pronta — está pela metade, do mesmo jeito que estaria se deixasse um teste quebrado. Colocar a atualização da doc na definição de pronto, e cobrá-la na revisão, é o que cria o dono que faltava. O dono não é uma pessoa nomeada para "cuidar dos docs"; é quem quer que aquele PR seja aprovado. O incentivo passa a estar alinhado com o fluxo normal de trabalho, em vez de competir com ele.

Há um limite prático nisso, e é justamente por ele que a referência de baixo nível deve ser gerada a partir do código sempre que possível. Documentação escrita à mão que espelha detalhes mecânicos — a assinatura exata de cada função, a lista de parâmetros de cada endpoint — vai divergir mesmo com toda a disciplina do mundo, porque é volume demais para revisar linha a linha. Deixe a máquina extrair isso de anotações, tipos e schemas, e reserve o esforço humano para o que a máquina não gera: o porquê, o contexto, o caminho de começar. A doc escrita à mão deve se concentrar onde o julgamento humano é insubstituível.

Doc desatualizada é pior que nenhuma#

Existe uma intuição confortável de que qualquer documentação é melhor que nenhuma — que um texto desatualizado ao menos "dá uma ideia". É o contrário. Documentação errada é ativamente pior do que a ausência de documentação, e entender por quê é o que justifica todo o rigor dos capítulos anteriores.

A ausência de doc é honesta; a doc errada mente com confiança. Quando não existe documentação, o leitor sabe que não sabe. Ele vai direto à fonte confiável — o código, os testes, uma pessoa — e trabalha com a incerteza à mostra. Quando existe documentação desatualizada, o leitor recebe uma afirmação com toda a aparência de autoridade: está escrita, está formatada, parece oficial. Ele age com base nela. E então perde tempo depurando um comportamento que a doc jurava ser outro, ou toma uma decisão sobre uma premissa que deixou de ser verdade há seis meses. O custo não é só o tempo perdido; é a confiança traída no momento em que ele mais precisava dela.

Uma única mentira contamina o documento inteiro. Basta o leitor descobrir uma afirmação errada para que todo o resto do documento fique sob suspeita. Se aquela seção estava desatualizada, como confiar na próxima? A partir daí, cada linha precisa ser verificada contra a realidade, o que é mais lento do que não ter documento nenhum — porque agora há o custo de ler mais o custo de desconfiar. É por isso que um documento noventa por cento correto pode ser pior que a sua ausência: os dez por cento errados envenenam os noventa que estavam certos, e o leitor não tem como saber, a priori, em qual grupo cada frase está.

A consequência prática é dura e liberta ao mesmo tempo: documente menos, mas mantenha o que documentar. É melhor ter cinco páginas nas quais o time confia cegamente do que cinquenta que todos leem com uma sobrancelha levantada. Cada documento que você cria é um passivo de manutenção — uma promessa de mantê-lo verdadeiro. Se você não vai manter, não escreva, porque a versão futura e falsa dele vai custar mais do que a sua ausência custaria. E quando uma doc já morreu sem chance de ressurreição, a atitude correta não é deixá-la lá "por via das dúvidas": é apagá-la. Deletar documentação errada é um ato de manutenção, não de desleixo. Uma pasta de docs menor e verdadeira é infinitamente mais valiosa que um arquivo gordo e mentiroso.

O que NÃO documentar#

Escrever menos e melhor exige saber onde não gastar tinta. Boa parte da documentação apodrece porque nunca deveria ter sido escrita — era esforço investido em capturar o que já estava disponível em outro lugar mais confiável ou o que muda rápido demais para valer a pena.

Não documente o que o código já diz claramente. Um comentário que repete a linha que ele antecede não informa nada e ainda mente na primeira vez que a linha muda e o comentário fica. Nomes bons de variáveis, funções e módulos são a primeira e melhor camada de documentação, e ela nunca sai de sincronia porque é o próprio código. Reserve os comentários para o que o código não consegue expressar: o porquê de uma escolha não óbvia, o link para o ticket que explica um workaround, o aviso sobre uma pegadinha que morderia o próximo leitor. Comentário bom explica intenção, não mecânica.

Não documente à mão o que pode ser gerado. Listas de endpoints, tabelas de configuração, assinaturas de função — tudo isso é derivável do código e deve ser derivado dele. Manter essas listas à mão é assinar um contrato de divergência: você garante que, em algum ponto, o documento vai contradizer a realidade. Deixe a geração automática cuidar do que é mecânico e mantenha o olho humano para o que exige julgamento.

Não transforme detalhes voláteis em documentação. Capturas de tela de interfaces que mudam a cada sprint, números de versão de cada dependência espalhados pelo texto, valores exatos de configuração que variam por ambiente — tudo isso envelhece em semanas. Quando o detalhe muda com frequência, aponte para a fonte viva dele em vez de copiá-lo: referencie o arquivo de configuração real, o painel real, em vez de transcrever um valor que vai mudar. Documentação deve capturar o que é estável; o volátil pertence à sua fonte.

Não documente processos que ninguém vai seguir. O guia de vinte passos que descreve o processo ideal de deploy, que na prática ninguém executa porque existe um script que faz tudo, é ficção. Ou o processo real é o script, e a doc deveria apontar para ele, ou o processo manual é mesmo necessário e deveria ser automatizado em vez de documentado. Documentar um ritual que a realidade não segue só cria uma discrepância entre o que está escrito e o que acontece — e o que está escrito perde, sempre. Frequentemente, a melhor resposta a "isso precisa ser documentado" é "isso precisa ser automatizado", e a automação vira a documentação executável que não pode mentir porque é ela que roda.

Fechamento#

Documentação que a equipe realmente usa não vem de escrever mais. Vem de tratar cada peça pelo que ela é. Um README curto que leva o próximo dev do clone ao rodando. Quatro tipos de doc que não se misturam, porque tutorial, how-to, referência e explicação servem a leitores diferentes. ADRs que capturam o porquê das decisões, a informação mais cara e mais perecível do sistema — exceto que, escrita, ela para de perecer. Referência gerada a partir do código, para não divergir. E uma disciplina simples por baixo de tudo: a doc mora perto do código, nasce no mesmo PR que a torna necessária e passa pela mesma revisão, de modo que atualizá-la deixa de ser um ato de virtude e vira parte de terminar o trabalho.

O resto é coragem para escrever menos. Cada documento é uma promessa de mantê-lo verdadeiro, e uma promessa que você não vai cumprir é pior do que não fazê-la — porque a doc desatualizada mente com a confiança que a ausência nunca teve. Documente o estável, o porquê, o caminho de começar. Aponte para a fonte viva de tudo que muda rápido. Automate o processo em vez de descrevê-lo. E quando um documento morrer sem conserto, apague-o sem culpa: uma pasta menor e verdadeira vale mais do que qualquer volume no qual ninguém confia. O objetivo nunca foi ter muita documentação. Foi ter a documentação certa, viva, no dia em que alguém precisar dela.