Documentação: fazer um texto ou um diagrama?

Continuando o assunto documentação, o primeiro pensamento é fazer um texto ou um tutorial. Mas em muitos cenários, um diagrama é mais eficiente do que várias palavras. Como exemplo, vou trazer dois cenários que tenho no meu local de trabalho. O primeiro cenário está ligado a parte de front-end. Temos um site interno para auxiliar as áreas de negócios em algumas tarefas como gerar um QR Code, hiperlink e outros. Isso foi feito internamente por questões de segurança e devido as leis. Nesse cenário, foi fundamental que fizéssemos um passo a passo. Esse tutorial foi feito escrito e contendo imagens para que as pessoas pudessem fazer os processos sem precisar pedir nossa ajuda. Talvez você possa achar isso estranho, mas nunca esqueça que o usuário é capaz de fazer impossível.

Agora vamos falar do segundo cenário. Esse cenário é mais legal, pois foram feitos vários diagramas. Os diagramas são como mapas dos microsserviços e como uma requisição percorre a arquitetura do meu setor. Sendo que cada parte da arquitetura tem um diagrama menor ou o microsserviço tem um diagrama a parte. Cada diagrama tem um determinado objetivo e com isso, identificamos se existe o uso de um sqs, sns, rabbit, banco de dados relacional ou sql, reddis ou outra ferramenta. Para ficar fácil imagina esse diagrama, pense como a planta de uma casa.

Pensando nos dois cenários que abordei acima, o conselho que posso lhe dar é: que você precisa entender a necessidade do que você vai documentar. Se seu serviço ou arquitetura tem uma complexidade alta ou é vasta, pode ser interessante fazer um documento em que o diagrama é complementado pela parte escrita. Se você nunca fez uma documentação, recomendo começar a brincar com o diagrama. Um programa que gosto de usar é o Draw.io, esse programa tem os ícones das ferramentas em nuvem. Com isso, se você usa nuvem da Google, AWS, Azure e outras, você pode usar o ícone para detalhar como seu microsserviço é executado ou se tem algum firewall, etc.

Se você não leu o primeiro texto, coloquei o link abaixo:

https://web.dio.me/articles/documentacao-um-trabalho-que-deixamos-de-lado?back=%2Farticles&page=1&order=oldest