E se a sua documentação se escrevesse sozinha?

Documentação que se escreve sozinha parece uma contradição. A documentação deveria ser uma atividade humana: um engenheiro entende algo, senta-se e explica-o em prosa. A ideia de que a documentação poderia se escrever sozinha sugere ou que a qualidade seria terrível (conteúdo de baixa qualidade gerado por IA) ou que seria superficial demais para ser útil (READMEs autogerados que ninguém lê).

Nenhuma das duas opções é o que documentação que se escreve sozinha realmente significa na prática.

Como realmente funciona

A premissa é de que o conhecimento necessário para uma boa documentação de engenharia já existe. Ele existe nas descrições de PRs onde os engenheiros explicam o que mudaram e por quê. Em conversas no Slack onde as equipes debatem decisões de arquitetura, discutem prós e contras e resolvem questões de design. Em gravações de reuniões onde as prioridades são definidas, as migrações são planejadas e os incidentes são revisados. Em mensagens de commit, documentos de design e comentários de revisão de código.

Atualmente, esse conhecimento é efêmero. A conversa no Slack some da tela em poucos dias. O PR é mesclado e esquecido. A gravação da reunião fica em uma pasta que ninguém revisita. O conhecimento foi criado, compartilhado e perdido, tudo dentro do período de uma semana normal de trabalho.

A documentação que se escreve sozinha captura esse conhecimento à medida que ele é criado e o estrutura em uma wiki persistente e pesquisável que se mantém atualizada conforme a atividade subjacente muda.

O processo funciona da seguinte forma:

Conecte suas fontes. Repositórios do GitHub, canais do Slack, gravações de reuniões, servidores do Discord. Esses são os locais onde o conhecimento de engenharia já está sendo compartilhado.

O sistema lê e sintetiza. À medida que novos PRs são mesclados, novas conversas acontecem e novas reuniões são gravadas, o sistema processa o conteúdo, extrai o conhecimento relevante para a engenharia e o integra em uma documentação estruturada.

A wiki se mantém sozinha. Quando um PR altera o funcionamento de um sistema, a documentação sobre esse sistema é atualizada. Quando uma conversa no Slack resolve uma questão de design, os documentos relevantes incorporam a decisão. A documentação permanece atualizada porque é derivada da mesma atividade que altera os sistemas subjacentes.

Os engenheiros revisam e refinam. O sistema produz o primeiro rascunho. Os engenheiros revisam, corrigem imprecisões, adicionam contexto e enriquecem a documentação com insights que o sistema automatizado não conseguiria deduzir. O papel do engenheiro muda de autor para editor, o que se torna uma tarefa de dez minutos em vez de uma sessão de escrita de duas horas.

Como é o resultado

A documentação gerada é estruturada, citada e editável.

Estruturada significa que ela segue uma formatação consistente: visões gerais do sistema, documentação de API, registros de decisões, históricos de alterações, wikis específicas de equipes. O formato é padronizado, o que significa que a documentação é navegável e previsível, independentemente de qual sistema ela descreva.

Citada significa que cada afirmação na documentação possui um link de volta para a sua fonte: o PR, a mensagem do Slack, o carimbo de data/hora da reunião. Um engenheiro que estiver lendo os documentos pode clicar para acessar o contexto original para verificar qualquer afirmação ou obter detalhes adicionais. É isso que diferencia a documentação que se escreve sozinha do texto gerado por IA: a documentação é fundamentada em atividades reais, não gerada a partir dos dados de treinamento de um modelo.

Editável significa que os documentos gerados são um ponto de partida, não um produto final. Os engenheiros podem modificar, reestruturar e fazer anotações nos documentos. O sistema aprende com essas edições, melhorando a geração futura.

O que ela não é

A documentação que se escreve sozinha não é um texto gerado por IA que recebeu um comando para "escrever a documentação para a nossa base de código". Essa abordagem produz uma prosa genérica, muitas vezes imprecisa, que parece um modelo de linguagem tentando adivinhar o que o seu sistema poderia fazer.

A documentação que se escreve sozinha é gerada a partir da sua atividade real de engenharia: PRs reais, conversas reais, reuniões reais. O resultado descreve o que realmente aconteceu, em vez do que um modelo acha que pode ter acontecido. As citações oferecem verificabilidade. A atualização contínua garante que o conteúdo esteja em dia. A revisão humana garante a qualidade.

A distinção é importante porque a confiança na documentação é frágil. Engenheiros que descobrem que documentos autogerados estão imprecisos vão parar de lê-los tão rapidamente quanto param de ler documentos escritos manualmente que ficaram desatualizados. A documentação que se escreve sozinha ganha confiança por ser verificável (toda afirmação tem uma fonte) e atualizada (os documentos são atualizados conforme o sistema muda).

As fontes

A documentação que se escreve sozinha pode se alimentar de vários tipos de fontes, e a cobertura melhora à medida que mais fontes são conectadas:

GitHub: Descrições de PR, mensagens de commit, comentários de revisão de código, discussões de issues. Eles capturam o que mudou e o porquê.

Slack: Discussões de design, debates de arquitetura, threads de resposta a incidentes, conversas sobre decisões. Eles capturam o raciocínio que não entra no código.

Reuniões: Planejamento de sprint, revisões de arquitetura, pós-morte de incidentes, sessões de onboarding. Elas capturam o contexto verbal que normalmente se perde.

Canais de engenharia: Canais dedicados de engenharia no Slack, servidores do Discord ou outras ferramentas de comunicação onde ocorrem discussões técnicas.

Quanto mais fontes conectadas, mais abrangente será a documentação e menor será a probabilidade de que conhecimentos críticos se percam nos espaços entre as ferramentas.

Perguntas frequentes

Quão precisos são os documentos gerados? A precisão varia de acordo com a qualidade da fonte. Descrições de PR com explicações claras produzem documentos melhores do que mensagens de commit de uma única linha. Discussões detalhadas no Slack produzem documentos melhores do que trocas de mensagens curtas. O sistema de citações permite que os engenheiros verifiquem qualquer afirmação checando a fonte original, e a etapa de revisão detecta imprecisões antes que elas se tornem oficiais.

Quanto tempo de engenharia a configuração exige? Conectar as fontes normalmente leva menos de uma hora. O sistema começa a gerar a documentação assim que as fontes são conectadas. O tempo contínuo de revisão é de cerca de dez a quinze minutos por semana por engenheiro, em comparação com as cinco horas por semana que a documentação manual costuma consumir.

Podemos controlar o que o sistema captura? Sim. Você escolhe quais repositórios, quais canais do Slack e quais categorias de reuniões o sistema lê. Canais privados, repositórios confidenciais e reuniões sigilosas podem ser excluídos.

Isso substitui o Confluence/Notion/nossa wiki existente? Pode substituí-los ou complementá-los. O sistema de documentação que se escreve sozinha produz uma documentação estruturada e pesquisável que atende ao mesmo propósito de uma wiki manual, com a vantagem de se manter atualizada automaticamente. O conteúdo da wiki existente pode ser preservado junto com os documentos gerados.

Leitura relacionada: Por que a documentação de engenharia é importante, O paradoxo da documentação, Por que engenheiros odeiam escrever documentação, Documentos autogerados vs Confluence. Páginas relacionadas: Documentos que se escrevem sozinhos, Para equipes de engenharia.