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 !