Fiz algumas perguntas nas redes sociais e ferramentas de comunicação como Twitter, LinkedIn, Slack, Discord e Telegram sobre como as pessoas costumam documentar a arquitetura de sistemas.
-
Vocês costumam desenhar diagramas para documentar a arquitetura dos sistemas que vocês constroem?
-
O que vocês costumam representar: código, infraestrutura ou ambos?
-
Quais ferramentas costumam utilizar: as gráficas (como Miro ou Excalidraw) ou as de texto (como Mermaid ou PlantUML)?
-
Quais tipos de diagramas vocês costumam utilizar? C4, UML, fluxograma, MER, BPM-N ou outros?
-
Onde vocês armazenam esses diagramas? Em markdown no próprio repositório do projeto ou em ferramentas como Confluence?
-
Em quais situações vocês veem a utilidade desses diagramas? Ao revisitar uma lógica complexa, durante o onboarding de novos funcionários e/ou outras situações?
-
C4 de modo geral. diagramas de sequência para fluxos importantes.
-
Infra.
-
Excalidraw + Mermaid e C4 autogerado por código.
-
Depende muito do que eu preciso elucidar, mas como eu citei sequência e iterações entre caixinhas para explicar fluxos sem se apoiar em nada de UML.
-
Diagramas da codebase no repositório. O resto depende de onde mora as documentações da empresa.
-
Onboarding, revisitar decisões do passado, ter clareza dos macro processos sem ler o código. Deixar outros times descobrirem mais sobre os sistemas sem precisar de pessoas ou trocas síncronas.
PS: Nunca é só isso ou tão simples assim, mas depende pesadamente do caso, projeto, maturidade da equipe e da empresa.
-
Sim.
-
Eu gosto de documentar infra e processos também.
-
Usamos o Excalidraw mais para brainstroming e o Mermaid e o PlantUML para documentar.
-
Vou na mesma linha do Alex. Eu costumo gerar os diagramas que eu acho que vão comunicar o que eu quero ou acho relevante comunicar. Não sigo muito uma receita de bolo de quais diagramas devem existir.
-
A gente costuma documentar no mesmo repositório que o código, mas temos também uma base de conhecimento no Confluence para documentações que não são relacionadas diretamente a um produto específico.
-
Onboarding, pré-planning (as tasks já podem sair do planing apontando para uma documentação do que precisa ser feito), comunicação assíncrona (não precisar explicar várias vezes a mesma coisa).
-
Sim, normalmente utilizo diagramas junto com RFCs para propor soluçōes e depois de aprovado implemento. Isso é mais para mudanças grandes.
-
Normalmente é mais high level, descrevendo como os serviços interagem com os outros e qual dependências de infraestrutura eles têm.
-
Utilizo Lucid Chart e PlantUML.
-
UML.
-
Git e Google Docs (colocando no Confluence os links).
-
Para o entendimento de toda a equipe sobre determinada mudança ou implementação mais complexa e também no onboarding.
-
Sim.
-
Ambos.
-
Aqui estamos utilizando o PlantUML e para coisas mais rapidas usamos o draw.io.
-
Aqui para arquitetura usamos C4, do level 1 ao 3, para documentação de estados utilizamos o diagrama de estados (UML) e para banco de dados MER.
-
O que está em código (PlantUML) utilizamos o próprio repositório do projeto para versionar.
-
- Sempre que vamos explicar a arquitetura para alguém o desenho é util, desde um onboarding até uma apresentação sobre o projeto.
- Os diagramas de estado nos auxiliam muito a manter a nossa máquina de estado documentada, especificando todas as transições que podem existir no fluxo. Usamos a documentação sempre que temos alguma dúvida sobre o fluxo de estados de um produto.
- MER e dicionário de dados: Principalmente para os times de dados entenderem os relacionamentos e conseguirem montar um data lake mais assertivo, sem que tenham que nos consultar para entender alguma coisa da nossa modelagem. Também em onboardings, fica muito fácil o entendimento das entidades do sistema e como se relacionam.
-
Para sistemas complexos, sim.
-
Já fiz para ambos, mas geralmente mais infra.
-
Pra coisas simples a médias, as de texto (Mermaid e até o nomnoml.com para coisas muito simples). Gosto também do draw.io, principalmente quando tiver que mostrar pra pessoas não técnicas por algum motivo.
-
UML, MER e fluxogramas.
-
Em um repositório de wiki.
-
Sim, sim e para algumas reuniões com clientes quando trabalhava em software house.
-
Lucid Charts.
-
Infraestrutura e documentação de tópicos que não são tem como explicar em diagrama.
-
Miro, Figma, Lucid Charts, Notion e Confluence.
-
O que fizer mais sentido.
-
O que fizer mais sentido.
-
- Hands over pois o mais importante é garantir que quem for assumir o ownership, tenha informações suficientes para perceber as decisões e etc.
- Pois, por exemplo, algumas coisas não consigo explicar como o porquê de usar terraform mas fica fácil colocar em um diagrama a big picture do que aquilo gera.
- Ao mesmo tempo, preciso garantir que tópicos importantes estejam documentados para que outras pessoas que assumam a minha posição percebam como e porque foi feito daquela forma.
- Na posição atual de arquitetura e DevOps, impossível vender ideias de arquitetura sem ppts e documentação, o porquê das minhas decisões e etc.
- O mais importante é tornar visível, seja qual for a ferramenta a fazer uso.
-
Só quando é algo complexo. Diagramas ajudam a visualizar melhor o sistema e a organizar melhor a arquitetura.
-
Ambos, depende do objetivo.
-
PlantUML.
-
Diagrama de classe, diagrama de sequência, normalmente UML. BPMN uso mais quando quero documentar algum processo interno da empresa.
-
PlantUML gera código, versiono. Por exemplo: https://github.com/nextcloud/deck/blob/master/docs/resources/BoardImport.yuml Na real este especificamente fiz com yUML, é outra ferramenta similar que conheci antes do PlantUML. PlantUML é mais interessante pois tem muito mais opções de diagramas.
-
Como comentei, para definir uma lógica mais complexa. Outro cenário é para documentar de forma visual uma arquitetura que pode soar um pouco complexa de se compreender, ajuda se isto estiver em alguma página de documentação para quem irá usar o código como consta no exemplo do link que mandei acima.
-
Tento sempre fazer, o nível de detalhe depende doq precisa ser explicado.
-
Depende da "audiência".
-
Só faço o desenho.
-
Junto ao código, depende do que eu fiz.
-
Praticamente sempre.
-
Sim.
-
Depende do escopo e complexidade do projeto. Atualmente uso o modelo C4 (https://c4model.com) e tem funcionado bem.
-
Depende do time. Já usei só sequence diagram, Lucid Chart e quando o time decidiu adotar o C4, o https://adrianvlupu.github.io/C4-Builder.
-
Todos eles, dependem do projeto. Raramente uso BPM-N, neste sentido, prefiro um event storming com os diagramas anteriores.
-
Prefiro o Confluence porque é um GED completo. Caso use o C4 builder ou ferramentas geradoras, mesclo com um VCS como o Git.
-
Em todas as situações. Ajuda a reduzir o bus factor, revisitar a lógica pré implementação e a participação do time de negócio.
-
Sim! Muito importante e diminui o tempo de onboarding de novos devs.
-
Infraestrutura principalmente, código quando é algo mais complexo.
-
Atualmente a maioria no diagrams.io e estou tentando mudar para o Archi para desenhar outros comportamentos.
-
Te falar que o que mais uso é o diagrama abaixo que não sei realmente um nome específico, chamo de diagrama de solução. Uso também UML para relacionamentos de banco e já usei BPM.
-
Confluence e também dentro dos README no Git.
-
Troca de conhecimento principalmente, comunicação com outros times e onboarding de novos membros.
-
Sim, quando é útil pra dar suporte à explicação de algum contexto, principalmente pra abranger diferentes formas de aprendizado.
-
Ambos, mas diria que tem uma terceira categoria, algo entre as duas opções que você listou. Basicamente o segundo nível do C4. Diagramas representando os contextos do domínio também são super interessantes pra dar suporte à decisões técnicas.
-
Ambas. Dependende do contexto. Quando escrevendo markdown (pra ADRs), prefiro usar Mermaid. O Miro é útil pra representar coisas mais complexas mas exige esforço maior pra manter atualizado.
-
Tenho gostado bastante do C4 (focando nos 2 primeiros níveis) mas depende da necessidade, né. As vezes um diagrama de sequência é o que você precisa.
-
Quanto mais próxima ao código melhor, pois é mais fácil de revisar e manter atualizado.
-
Tudo o que você citou. Adicionaria: explicação de mudanças descritas em ADRs e propostas de reorganização de sistemas (ou partes deles).
-
Raramente, geralmente desenho os diagramas no momento da explicação/tentativa de solucionar um problema.
-
Tudo, mas sempre o diagrama é focado em um contexto específico. Fazer um "mega" diagrama geralmente não ajuda em muita coisa.
-
Quais ferramentas costumam utilizar: lousa, janela, celular (foto), Draw.io e Miro.
-
Caixinhas, fluxograma. Se tiver muito inspirado faço com uma notação mais padronizada.
-
Conflunce ou algo similar, é mais simples de editar. Quando é no código geralmente um markdown.
-
Geralmente onboarding e também no offboarding daquele funcionário pica das galáxias que sabia a porra toda. Me utilizo também de outros documentos gerados no decorrer do trabalho, como os tickets do Jira para entender o porque certos comportamentos do sistema.
-
Sim.
-
Se é diagrama de sistemas não entro em mérito de código, mas de microserviços e infra.
-
Diagrams.net (finada draw.io), mas em alguns casos já usei PlantUML
-
UML e fluxograma.
-
Confluence.
-
Para sistemas mais complexos, os diagramas ajudam muito a deixar todo mundo na mesma página. E claro que no onboarding são muito úteis.
-
Sim.
-
Código, infra e banco.
-
Mermaid, Diagrams.net, .dbml (banco), .apib (blueprint api).
-
C4, MER, fluxograma.
-
O que é possível no Git, o que é ferramenta externa, link no readme ou página do projeto em lugares tipo Confluence (aqui temos o nosso playbook).
-
Onboarding, discussões técnicas em guildas, apresentações do projeto para outras equipes. E facilita definir contratos e integrações entre serviços.
-
Sim.
-
Quando tive a oportunidade criei diagramas do todo, infra bem como o código, afinal nós precisaríamos ver um ensaio de nossa orquestra sem uma requisição.
-
Mistura de C4 + Fluxo.
-
Criar arquivos .adr.md no repositório/camada de domínio onde poder ficar mais próximo da solução de contexto.
-
Nas duas situações, em onboardings as pessoas rapidamente podem ser convergidas a entregarem rápido, e claro na revisita de uma lógica complexa sem dúvidas.
-
Sim.
-
Não coloco nada relacionado ao código, mas to estudando o C4 para tentar colocar a representação.
-
Uso mais o Miro, mas já usei o draw.io, estou dando uma olhada no PlantUML para usar o modelo C4 que comentei acima.
-
Usamos fluxograma.
-
Confluence.
-
Em apresentações, onboarding para pessoa se situar, refinamento para ver em quais pontos estamos atuando e oq impacta.