Gestão de documentação

Uma vez instalei um wiki (da mediawiki) apenas pra equipe de desenvolvimento. Cada um colocava ali o que precisava documentar. Fez bastante sucesso, outras áreas também começaram a incluir, acabamos liberando pra toda empresa, mas apenas na intranet. Depois de um tempo, a documentação das aplicações também foi incluída e abriram uma extranet pros clientes acessarem o wiki.

Tempos depois trabalhei em outra empresa, dei a mesma ideia. Mas aí os arquitetos decidiram que apenas os arquitetos e a infra poderia atualizar o wiki - segundo eles "pra não virar uma zona". Os desenvolvedores tinham que formatar um documento e repassar pra arquitura e então eles atualizarem. Nem preciso dizer que foi um fracasso. Bando de patetas.

Olá SrVinicius,

Na minha opinião: Acredito que não haja resposta "certa" mas aquela que resolve determinada tarefa. Principalmente a depender do contexto.

Exemplo, seja um projeto com apenas 2-10 desenvolvedores. Qual é sentido de ter uma documentação super detalhada de cada função ? Acredito que nenhuma. Exceto se for um serviço que expõe uma API publica ou privada com centenas de usuários.

Caso contrario de uma empresa com muitos funcionários, cada trecho de código não documentado vira tempo gasto ao precisar ser analisado ex. por um novo desenvolvedor contratado.

Para além disso, na minha percepção, hoje temos uma lack na documentação de infraestruturas cloud que são dinâmicas e complexas.
Nota: Existem sim algumas alternativas ! como a CloudCraft ou Quaternion ( paragrafo próprio : sou eu que estou tocando esse projeto caso queira contribuir seja bem vindo ! )

Bom, dado esses outros pontos existem alguns frameworks como documentação como principio ou DDT ( esse é para testes, mas colabora na documentação ) para lidar com dinâmica código x qualidade.

Espero ter esclarecido alguma coisa !