Como as empresas produzem documentação de software hoje em dia? Se produzem, é todo o sistema? ou algumas partes? Se é algumas partes, qual critério que define qual parte será documentada? Quais técnicas/ferramentas essas empresas costumam utilizar? Utiliza-se versionamento em documentação? e que Linguagens utilizam? UML seria uma das? Como funciona isso? imagino que deva ter alguma estrátegia adotada dado esses sistemas gigantes e complexos.
Geralmente as documentações de sistemas seguem algum padrão de mercado. Um dos padrões adotados na estrutura aqui do GB é o C4 Model
Nesse padrão temos basicamente quatro níveis de documentação de arquitetura: Contexto > Container > Componente > Código.
A idéia de documentar os sistemas é passar o entendimento das escolhas que foram tomadas na construção para o restante da organização, então vc deve buscar esse contexto quando pensa em como gerar uma documentação de sistema.
A maior parte das aplicações possui um swagger como “documentação”.
Existem várias ferramentas utilizadas para documentar... Minha squad, por exemplo, documenta tudo no GIST e segue o fluxo de desenvolvimento padrão para aprovar documentos (inclusive enviando PRs, esperando pelo menos 2 aprovações e fazendo o merge na main quando finalizado).
UML é sim um dos padrões utilizados para documentar sistemas, muito comum criar diagramas de contexto, classe, caso de uso e usar um modelo UML para isso.
E pra finalizar, como escolher o que documentar? Geralmente quando se pensa nas soluções vc já tem algum tipo de documentação como um ADR e isso já começa a constar como documentação do seu sistema. Um desenho de arquitetura mais macro e ai pegando as partes principais que serão consumidas por outros times geralmente é o caminho natural de escolha para documentação mais robusta. Mas vai do contexto e necessidade, a melhor prática é sempre ter documentação suficiente para que as pessoas possam entender de forma simples o que uma aplicação faz.
by latan