Práticas e ferramentas para manter documentações atualizadas

Uma das ferramentas que mais vejo sendo usada com eficácia, quando todas as pessoas sabem usar e estão comprometidas é uma wiki, em geral o MediaWiki mesmo.

O Github também pode ser usado já que ele tem características de wiki, embora bem menos poderoso, mas mais simples e agradam mais algumas pessoas, mas só costuma valer para quem já o paga, o gratuito dá mas fica bem mais limitado, o que pode ser suficiente.

Em alguns casos é melhor usar ambos, cada um com a parte que ele faz melhor.

Tem gente que usa ferramentas padrões diversas como Notion e assemelhados.

Ferramentas específicas em geral só fazem bem uma tarefa e não o que deseja que é centralizar tudo o que é necessário.

Se precisar de algo muito mais poderoso e flexível, que atenda bem sua necessidade, não tem alternativa a não ser fazer uma ferramenta.

Reforço, saber usar e comprometimento é o que mais importa. Cultura pesa mais que ferramenta, como diz metodologias ágeis. Com isso até um monte de arquivos txt e png em diretórios públicos pode servir. Em lugares que a cultura diz que agilidade é entregar rápido, nada dará certo. E está sumindo os lugares que não pensam assim.

S2

---

Farei algo que muitos pedem para aprender a programar corretamente, gratuitamente (não vendo nada, é retribuição na minha aposentadoria) (links aqui no perfil também).

Aqui na firma, estamos experimentando uma abordagem que busca atacar justamente essa desconexão entre documentação e desenvolvimento, seguindo a filosofia de "docs as code".

O nosso sistema envolve:

DSL (Domain Specific Language) e CNL (Constrained Natural Language): Desenvolvemos uma linguagem específica para o nosso domínio e um subset de linguagem natural com regras estritas. Isso nos permite escrever de forma precisa e menos ambígua sobre nossos sistemas, regras de negócio e APIs.

Embutido em Markdown: Essa DSL/CNL é escrita diretamente em arquivos Markdown. Isso facilita a escrita para os desenvolvedores, permite o uso de formatação familiar e, crucialmente, possibilita que a documentação seja versionada junto com o código (no Git).

Compilador Customizado: Temos um "compilador" próprio baseado no pandoc, um pouco na linha do que o LaTeX faz com arquivos .tex) que processa esses arquivos Markdown "enriquecidos". Ele interpreta nossa DSL/CNL e gera automaticamente documentos formais (html e pdf), relatórios, diagramas.

Escrita na Mesma IDE: O ponto chave aqui é que os desenvolvedores escrevem e atualizam essa documentação dentro do mesmo IDE que usam para codificar. Isso reduz drasticamente a barreira de contexto e incentiva atualizações mais frequentes, pois a documentação está ali, ao lado do código que está sendo alterado.

Nosso "pipeline de docs as code" customizado, então, permite que a documentação evolua organicamente com o código, passe pelos mesmos processos de code review e versionamento. A meta é que, ao mudar o código, a mudança na documentação seja uma parte natural do mesmo commit.

Uma grande inspiração para abordagens como essa, e que talvez te interesse, é o G3doc do Google.

Hmmm, ao meu ver é falta de pesquisa da sua parte. Eu já implementei 2 ferramentas de documentação onde estou trabalhando atualmente e eu não as conhecia até fazer pesquisas um pouco mais profundas até achar anuncios da ferramenta na internet ou Github

Wiki.js, no qual usamos pra fornecer documentação técnica pros clientes do ERP de saúde que produzimos
Outline, para documentação interna do time de software que é basicamente uma forma de rodar o Notion no Docker pois as funcionalidades é 90% iguais

Não sou um usuário high-end de git, uso o basicão dele e entendo alguns comandos avançados, mas uma coisa q me veio na cabeça (não sei se já existe algo implementado), é se o git tivesse um tipo de verificador dos históricos de documentações. Seria uma ferramenta extra do git (ou até uma outra ferramenta q associe a ele), onde permite que o usuário (a gente) rodar um comando para checar se existe algum método/classe q teve alteração. Se a documentação não foi alterada desses casos de alteração, ele mostraria um alerta, sendo q pode ter 2 ações do usuário, ou aceitar q não precisa de atualização, ou precisa atualizar a documentação, sendo q nesse segundo ele precisaria atualizar a documentação antes de passar pra frente.

Isso é só uma ideia louca q tive agora com base no q o GheistLycis disse acima, não pretendo ir mais a fundo, mas ter esse tipo de ferramenta seria mto legal para dar suporte a nós, para sempre estar atento as nossas documentações. E por ser optativo, usaria quem quiser, pois não acho q isso deva ser um impeditivo obrigatório para entrega de uma PR.

Edit: dando uma rápida busca pelo copilot, ele disse q existe sim ferramentas q faz isso. Como não usei, não posso dizer mto sobre a qualidade e eficácia, mas pode ser uma mão na roda qm souber integrar isso.

Pra mim, documentação faz parte do código-fonte. Porque a longo prazo, é a única coisa que será mantida, atualizada e consultada. Então, toda documentação do projeto é registrada como comentários ou mesmo arquivos README (e outros .md) dentro do repositório.

Algumas vezes será gerada documentação de API, como JavaDoc, mas sempre do repositório para fora. Um script de build gera o HTML, e publica na web. Com um único ponto de atenção (repo), fica bem mais prático manter tudo atualizado.

Outros artefatos que não sejam considerados código, como documentos, planilhas, imagens, etc, ficam no diretório docs/, dentro do mesmo repositório. Mas seria apenas para registro histórico, ou fins de auditoria. Qualquer coisa mantida fora do repositório, um diretório compartilhado na rede, por exemplo, não será atualizado no médio prazo. Quem diz que atualiza, em minha experiência, está iludido ou mentindo.