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.