Por que o Confluence não funciona (e o que funciona)

Se você trabalha na área de engenharia há mais de alguns anos, já vivenciou o ciclo de vida do Confluence. Uma nova equipe ou uma nova iniciativa cria um espaço no Confluence. Engenheiros motivados escrevem a documentação inicial: visões gerais de arquitetura, documentos de design, guias de processos. O espaço parece ótimo nas primeiras semanas.

Depois, a manutenção para. PRs são enviados sem as atualizações de documentação correspondentes. Mudanças na arquitetura não são refletidas. Novos engenheiros entram e descobrem que os documentos descrevem um sistema que existia há seis meses. Engenheiros seniores alertam os novos contratados que "a wiki está quase toda desatualizada" e sugerem perguntar em vez de ler. O espaço no Confluence se torna um cemitério de boas intenções: páginas bem estruturadas e com formatação agradável que descrevem uma versão da realidade que não existe mais.

Este não é um problema específico do Confluence. É um problema de qualquer sistema de documentação que dependa de humanos escrevendo e mantendo documentos manualmente. Wikis do Notion ficam desatualizadas da mesma forma. Google Docs acumulam divergências de maneira idêntica. Páginas do GitBook apodrecem no mesmo ritmo. A ferramenta não é o problema. O modelo é.

Por que a documentação manual falha

A documentação manual falha porque exige que um ser humano realize um trabalho que não produz valor visível e direto, e porque o esforço é contínuo, em vez de ser feito uma única vez.

Escrever um documento é um custo único. Mantê-lo atualizado é um compromisso indefinido. Cada sprint, cada refatoração, cada mudança de arquitetura gera trabalho de manutenção de documentação, e esse trabalho nunca é priorizado porque não entrega funcionalidades, não corrige bugs e não move métricas que as pessoas estejam acompanhando.

O resultado é que mesmo equipes com forte cultura de documentação acumulam débito de documentação constantemente, pois a taxa de alteração do sistema sempre excede a taxa de manutenção da documentação. Quanto mais rápido você entrega, mais rápido os documentos ficam desatualizados, e o paradoxo da documentação garante que as equipes com mais coisas para documentar sejam justamente as menos capazes de acompanhar o ritmo.

O design específico do Confluence piora isso de algumas maneiras. Sua busca é fraca o suficiente para que os engenheiros muitas vezes não consigam encontrar documentos mesmo quando eles existem. Sua interface de edição desestimula atualizações rápidas porque o editor de páginas é pesado em comparação com a digitação em um arquivo de código. E sua organização depende de alguém mantendo ativamente a estrutura do espaço, o que é mais um fardo de manutenção que ninguém prioriza.

A mudança de modelo

A alternativa não é uma ferramenta de wiki melhor. É um modelo diferente de como a documentação é criada.

No modelo manual, um engenheiro realiza o trabalho e depois escreve sobre ele em um sistema separado. A escrita é uma segunda tarefa além da primeira, separada no tempo, separada no contexto e dependente da motivação do engenheiro para fazê-la.

No modelo de escrita automática, a documentação é gerada a partir do próprio trabalho. Descrições de PRs tornam-se documentação de mudança do sistema. Conversas no Slack tornam-se registros de decisões. Discussões de reuniões tornam-se documentos de planejamento e arquitetura. O engenheiro não escreve documentos. O sistema os escreve a partir da entrega existente do engenheiro.

Essa mudança importa porque elimina os dois modos de falha que matam a documentação manual: o problema de motivação (engenheiros não querem escrever documentos) e o problema de atualização (os documentos ficam defasados porque a manutenção não é priorizada).

Como é uma wiki de escrita automática

Uma wiki de engenharia de escrita automática é uma base de conhecimento estruturada e pesquisável que se mantém atualizada a partir de fontes conectadas.

A documentação do sistema é atualizada à medida que os PRs são mesclados, refletindo o estado atual de cada sistema, em vez de mostrar o estado de quando alguém se lembrou pela última vez de atualizar a página da wiki.

Registros de decisão são criados a partir de discussões no Slack onde as escolhas de arquitetura são debatidas e resolvidas, preservando o raciocínio junto com a decisão.

Materiais de onboarding permanecem atualizados porque são derivados das mesmas fontes que descrevem o sistema atual, em vez de serem um retrato estático de quando a última contratação motivou alguém a atualizá-los.

Históricos de alterações são compilados a partir de PRs e conversas, fornecendo uma linha do tempo de como cada sistema evoluiu e por quê.

Cada afirmação na documentação tem um link de volta para a sua fonte, o que significa que os engenheiros podem verificar qualquer coisa clicando no PR original, na mensagem ou na transcrição da reunião. Essa arquitetura de citações é o que diferencia os documentos de escrita automática de textos gerados por IA: a documentação é baseada em evidências, e não em inferências.

A migração

Mudar do Confluence para uma wiki de escrita automática não exige a migração de todo o conteúdo existente no primeiro dia. A abordagem pragmática:

Conecte suas fontes de engenharia (GitHub, Slack, reuniões). Permita que o sistema comece a gerar documentação a partir da atividade atual. Use a wiki de escrita automática para as novas documentações daqui para frente. Mantenha o espaço existente no Confluence como um arquivo legado para referência histórica e deixe-o morrer naturalmente à medida que a wiki de escrita automática se torna a principal referência da equipe.

Em poucas semanas, a wiki de escrita automática conterá a documentação atual gerada a partir da atividade em tempo real, enquanto o espaço no Confluence conterá a documentação histórica de relevância cada vez menor. A transição acontece de forma orgânica porque os engenheiros gravitam em torno da fonte em que confiam, e a fonte que permanece atualizada automaticamente ganha confiança mais rápido do que aquela que exige manutenção manual.

Perguntas frequentes

Investimos muito na nossa configuração do Confluence. Temos que abandoná-la? Não. A wiki de escrita automática lida com as novas documentações daqui para frente. Seu conteúdo atual no Confluence permanece acessível como referência histórica. Com o tempo, os engenheiros naturalmente passarão a usar por padrão a fonte mais atualizada e confiável, mas não há necessidade de uma migração forçada.

A qualidade do resultado é comparável à de documentos manuais bem escritos? Para documentação factual (o que o sistema faz, como mudou, o que foi decidido), a qualidade é comparável ou melhor, porque o sistema automatizado captura de forma abrangente, enquanto a documentação manual captura de forma seletiva. Para documentação narrativa (filosofias de arquitetura, princípios de design, cultura da equipe), a escrita humana ainda é superior. O melhor resultado é uma cobertura automatizada de documentos factuais com documentos narrativos escritos por humanos sobrepostos.

Como isso lida com informações conflitantes? O sistema usa a recência e a autoridade da fonte para resolver conflitos. Um PR mesclado ontem tem precedência sobre uma mensagem do Slack de três meses atrás. Os conflitos são sinalizados para revisão humana quando o sistema não consegue resolvê-los automaticamente.

Leitura complementar: Entendendo documentos de escrita automática, O paradoxo da documentação, Por que engenheiros odeiam escrever documentação. Páginas relacionadas: Documentos de escrita automática, Para equipes de engenharia, Fabric vs Confluence.