Nos últimos 15 anos, trabalhei em dezenas de projetos de software, e quase sempre a documentação era terrível. Os desenvolvedores subestimam a necessidade de documentação porque pensam que já entendem tudo. Os gerentes subestimam isso porque assumem que os desenvolvedores podem simplesmente ler o código e entender o projeto em algumas horas. Mesmo quando as pessoas não subestimam a documentação, muitas vezes não têm tempo e capacidade para fazê-lo.A visão geral precisa e atualizada geralmente fica na cabeça dos desenvolvedores seniores, que já carregam muitas responsabilidades. Não há cultura compartilhada ou intuição sobre o que deve ser documentado e o que é óbvio. Os desenvolvedores muitas vezes adicionam comentários para funções triviais ou descrevem parâmetros quando nomes ou tipos de variáveis mais claros teriam resolvido o problema. Talvez a documentação seja obsoleta? Só , indicando que muitas equipes tratam a documentação como uma “formalidade opcional” 4% das empresas sempre documentam seus processos https://www.bptrends.com/bpt/wp-content/uploads/2015-BPT-Survey-Report.pdf/ Ao mesmo tempo, temos fortes evidências de que sem boa documentação o negócio só perde uma enorme quantidade de tempo-dinheiro: “Documentação insuficiente” citada por 41% dos desenvolvedores como a principal causa de tempo desperdiçado, com 69% dos desenvolvedores perdendo 8+ horas por semana a tais ineficiências (montando para ~$ 18,5 milhões em produtividade anual perdida por 1.000 desenvolvedores) https://newsletter.getdx.com/p/state-of-developer-experience-2024 O embarque de um novo engenheiro leva de 3 a 9 meses, muito dependendo da documentação https://stripe.com/files/reports/the-developer-coefficient.pdf A falta de documentação é um componente importante da dívida técnica (https://www.informit.com/store/economics-of-software-quality-9780132582209) Um experimento com mais de 30 programadores mostrou que a falta de documentação causou cerca de 21% mais tempo gasto em entender o código durante tarefas de manutenção https://hci.com.au/get-documentation-budget/ Então, qual é a barreira real por trás de uma falta tão generalizada de documentação? No brilhante trabalho de Andrew Forward “Documentação de Software – Construção e Manutenção de Artefatos de Comunicação” fizeram uma boa pesquisa sobre as razões reais. External Factors Influencing Documentation Quality Como você pode ver, a falta de tempo e orçamento correlaciona com a frustração de que o esforço de documentação pode se tornar inútil e rapidamente desatualizado. Portanto, se reduzirmos o esforço manual e resolvermos o problema da documentação se tornando obsoleta, podemos dar um passo significativo em frente. A comunidade de desenvolvedores já introduziu abordagens como o Javadoc e ferramentas semelhantes que geram documentação automaticamente a partir de assinaturas de código. Portanto, ainda precisamos de documentação bem escrita, atualizada e legível pelo homem. O verdadeiro desafio é que a documentação não é uma entrega única, mas uma Mesmo que uma equipe escreva bons documentos no início, o código evolui mais rápido do que os hábitos de documentação.Sem sincronização contínua, a documentação se torna enganosa – o que é ainda pior do que não ter nenhum. Artefato Vivo Isso significa que o botão não é documentação, mas . Escrevendo Mantê-lo correto Soluções O que A IA é realmente boa em combinar padrões simples entre código e documentos.Existem algumas boas soluções onde você pode automatizar a deriva de documentação através da IA: Merge request rules, pointing agent to existing documentation and changed code base Claude Code documentation agent that keeps project docs up to date with Docusaurus. npx claude-code-templates@latest --agent=documentation/docusaurus-expert --yes Esta abordagem funciona bem para: Atualização de descrições de alto nível Resumo do Código Intent Reescrever frases desatualizadas Recuperar o contexto narrativo perdido No entanto, a AI tem limitações claras: Ele luta para detectar inconsistências estruturais (por exemplo, inv vars não documentados, portos, bandeiras CLI, bandeiras de características). Pode alucinar, especialmente quando os documentos são incompletos ou ambíguos. Ele não produz controles deterministas rastreáveis - cada corrida pode gerar um resultado ligeiramente diferente. Ele não pode dizer com confiança o que é importante e o que é ruído sem conhecimento de domínio. Em outras palavras, o AI pode ajudar Ainda não é confiável como um . rewrite and improve text source of truth validator Verificação estática Ferramentas como Resolve este problema tratando a documentação como algo que deve ser monitorado continuamente, assim como a qualidade do código ou o drift da infraestrutura. Ele funciona puramente algoritmicamente para não ser afetado por alucinações, embora falsos positivos ainda sejam possíveis. Duque Ducku trabalha extraindo sinais estruturais do seu repositório - variáveis de ambiente, rotas de API, pontos de entrada de serviço, importações de módulos, estrutura de diretório, chaves de configuração - e comparando-os com o que é referenciado em seus READMEs e wiki. Capacidades atuais Verificação de presença de entidade: Detecta quando variáveis de ambiente, chaves de configuração, portas, rotas da API ou nomes de scripts aparecem na documentação, mas não no código (e vice-versa). Cobertura de entidades paralelas: identifica grupos de itens semelhantes (serviços, empregos ETL, manipuladores lambda, comandos CLI) e marca adições não documentadas. Análise de módulo morto: Detecta arquivos que não são importados / usados em qualquer lugar - seja pontos de entrada que merecem explicação ou artefatos obsoletos. Verificação de integridade de URL: Detecta links quebrados ou desatualizados para recursos internos ou externos. Consistência de feitiço e estilo: higiene básica que normalmente é ignorada. Isso já é o suficiente para reduzir uma grande parte do fluxo de documentação silenciosa em projetos reais. CONCLUSÃO A documentação não falha porque os engenheiros são descuidados. que o mantém alinhado com o sistema que ele descreve. Código tem testes. Infraestrutura tem detecção de drift. CI tem portões de política. Documentação, na maioria das equipes, não tem nada. no feedback loop A IA pode melhorar a expressão e restaurar o contexto, mas não pode dizer de forma confiável se a documentação é As verificações estáticas, por outro lado, podem validar o alinhamento factual, mas não podem explicar a intenção ou a lógica do domínio. correct Ambos juntos podem trazer o que você precisa.
