image

Bootcamps ilimitados + curso de inglês para sempre

80
%OFF
Felipe Depaula
Felipe Depaula11/07/2024 21:57
Compartilhe

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

    Compartilhe
    Recomendados para você
    Microsoft 50 Anos - Prompts Inteligentes
    Microsoft 50 Anos - GitHub Copilot
    Microsoft 50 Anos - Computação em Nuvem com Azure
    Comentários (1)
    Regilene Silva
    Regilene Silva - 12/07/2024 09:37

    Oi, Felipe! Estou gostando demais dos teus textos sobre documentação. Como e gosto muito de saber os 'por menores' das coisas, me interessei pelo 'levantamento de requisitos, regras de negócio, KPI, processo de análise de negócio em geral' justamente para saber de onde vem os dados, quais são relevantes pra empresa/usuário e o que ela/ele deseja atingir. Percebi que a curva de aprendizados das ferramentas em si é bem curta, mas lógica do negócio, ter perfil mais analítico, ter ferramentas pra fazer o levantamento de requisito... aí são outros 500. Inclusive, vi esses dias a entrevista de um empresário sobre como os atrasos na entrega muitas vezes se relaciona ao fato de que o time de 'TI' não está alinhado ao 'Negócio'. Enfim, textos muito relevantes.