Como desenhar diagramas de arquitetura de software (2022)

 (terrastruct.com)
3 pontos por GN⁺ 2023-10-28 | 1 comentários | Compartilhar no WhatsApp
  • Um bom diagrama de arquitetura mantém a comunicação de ideias e a colaboração por mais tempo por meio do nível correto de abstração, da atualização constante e da eliminação de ambiguidades, e não de enfeites
  • O princípio básico é minimizar a distância entre vizinhos, mantendo elementos conectados próximos uns dos outros; conforme o diagrama cresce, torna-se necessário repetir o ciclo de apagar e redesenhar
  • A simetria não apenas causa uma boa impressão visual, mas também reforça o significado, como ao posicionar entradas de um lado e saídas do outro
  • Manter o alinhamento central das formas faz até conceitos complexos parecerem menos complexos e evita que o layout geral se desorganize ao adicionar novos elementos
  • Grupos de contêineres com rótulos mostram de relance separações de ambiente como AWS e Azure, abstrações como implementações de ReaderWriter e agrupamentos de objetos relacionados como Cores

Condições para um diagrama duradouro

  • Um bom diagrama não é apagado quando a reunião termina; ele pode continuar sendo usado depois como ponto de referência para discussões e perguntas futuras
  • Diagramas que permanecem úteis por muito tempo têm algumas condições em comum
    • Os elementos precisam estar no nível correto de abstração
    • Precisam ser mantidos atualizados
    • Não podem ter ambiguidades
  • A mesma entidade e relação podem ser desenhadas de várias formas, mas alguns layouts ajudam a colaboração ao longo do projeto, enquanto outros desaparecem quando a reunião termina
  • A beleza aqui não significa decoração como sombras ou cantos arredondados, mas sim uma beleza funcional que transmite ideias de forma eficaz

Princípios para criar um layout fácil de ler

  • Minimizar a distância entre vizinhos

    • A regra básica é desenhar nós conectados próximos uns dos outros
    • Em diagramas pequenos isso é fácil, mas, à medida que o diagrama cresce e novas conexões são adicionadas, essa propriedade tende a se perder
    • Assim como, ao encontrar um caso de borda no código, você corrige a parte relacionada, ou, ao perceber um item faltando em um documento, você revisa a frase, diagramas documentais também devem ser apagados e redesenhados quando necessário
    • Em entrevistas, o custo de redesenhar pode ser um problema, mas, se o documento será usado por várias pessoas ou equipes, iterar várias vezes leva a um diagrama melhor

  • Buscar simetria

    • A simetria contribui fortemente para a impressão estética de um diagrama, e o cérebro humano tende a preferir simetria visual, como em rostos
    • Mesmo que todos os nós estejam o mais perto possível de seus vizinhos, se faltar simetria o desenho pode parecer levemente torto
    • Mesmo que a distância entre vizinhos de alguns nós aumente um pouco, uma versão simétrica pode ser mais agradável de ver
    • Colocar as entradas de um lado e as saídas do outro reforça, junto com a simetria, o significado do diagrama

  • Alinhamento central

    • O alinhamento é um fator importante para fazer o diagrama parecer organizado
    • Um diagrama organizado torna os conceitos mais claros, enquanto um diagrama bagunçado faz os conceitos parecerem mais complexos
    • Se você começar colocando formas aleatoriamente em uma tela em branco, o restante do layout também tende a continuar aleatório
    • Como o alinhamento só faz sentido entre duas ou mais formas, mantê-lo sempre que novos elementos forem adicionados faz o diagrama naturalmente ficar mais limpo
    • Muitas vezes a simetria gera alinhamento, mas nem sempre

  • Usar grupos de contêineres

    • Dividir o diagrama em várias áreas com rótulos facilita para quem vê entender a estrutura
    • Os contêineres podem adicionar as seguintes informações ao diagrama
      • Adicionam contexto, como em “estes serviços estão na AWS, e estes serviços estão no Azure”
      • Mostram abstração, como em “todos estes são implementações de ReaderWriter”
      • Agrupam objetos relacionados, como ao reunir core 1, 2, 3 e 4 em um contêiner “Cores”

Itens que continuam na próxima parte

  • A Parte 2 aborda os seguintes temas
    • Desenho de caminhos de arestas
    • Tamanho e posição de rótulos
    • Cores
    • Ícones

Leituras relacionadas

1 comentários

 
GN⁺ 2023-10-28
Opiniões no Hacker News

  • Gosto bastante de criar diagramas com D2. É parecido com mermaid.js, mas tem mais opções de formatação e, pessoalmente, acho a sintaxe melhor
    Também escrevi um texto curto sobre isso: https://victorbjorklund.com/build-diagrams-as-code-with-d2-d...

    • Sinto que diagramas não deveriam ser bonitos. Por exemplo, cores devem ser usadas para transmitir significado, não como uma escolha estética ou artística
      Sei que diagramas de software feios não são agradáveis de ver, mas enfeitá-los é parecido com colocar curvas em um gráfico de linhas. Visualmente pode parecer melhor, mas atrapalha os dados que você quer comunicar
    • Segui o exemplo e ficou muito legal, mas, ao contrário do guia, foi renderizado de cima para baixo, não da esquerda para a direita
      Renderizei o primeiro exemplo x -> y como SVG e abri só o SVG no navegador; procurei na documentação inteira como alinhar a saída, mas não encontrei
      Parei de usar porque a documentação dizia uma coisa e o resultado real era outro. Pesquisando por "d2lang connection left to right", cheguei a https://d2lang.com/tour/layouts/, mas isso não parece estar ligado a partir da documentação de visão geral, então incluí-lo ajudaria os visitantes
    • https://flowchart.fun/ me ajudou a desenhar fluxogramas muito rapidamente para entender processos de sistemas. O melhor foi ser intuitivo e permitir iterações rápidas, e o CSS personalizado para estilização também foi bem útil
      Para fluxogramas, é uma das ferramentas de diagramação baseada em texto mais fáceis e rápidas que já usei
    • O D2 tem um motor de layout tala muito bom, mas é preciso uma licença paga para usá-lo. Os outros dois motores não são tão bons
    • Gosto do mermaid e uso com frequência, mas vou dar uma olhada no D2 também. Vejo diagramas declarativos como uma ferramenta poderosa para capturar pensamentos em uma forma legível e permitir versioná-los como qualquer outro texto

  • Quando um sistema começa a mudar, diagramas bonitos ficam muito difíceis de manter. Imagine adicionar uma nova caixa no meio de um diagrama já complexo: pode levar uma hora para realinhar tudo
    Nos anos 2020, provavelmente é melhor usar o tempo dos desenvolvedores para gerenciar diagramas como código: https://www.ilograph.com/blog/posts/its-time-to-drop-drag-an...

    • Sempre brinco que 10% de fazer diagramas é criar o diagrama em si, e 90% é alinhar setas
      Mas, na verdade, acho que não é brincadeira
    • Mantive um modelo C4 para importar e exibir no structurizr.com e, sinceramente, não foi divertido. Só o código não dava a compreensão intuitiva e a visão geral que se obtém no diagrama, e também não havia uma pré-visualização local rápida, então era preciso enviar o código ao servidor
      O pior é que, ao adicionar uma nova caixa, normalmente era necessário realinhar todas as setas. Como resultado, o diagrama não se mantinha continuamente atualizado
      Para diagramas de sequência, foi melhor quando usei plantML. O trabalho em si era mais fácil, então a saída do interpretador geralmente era utilizável sem intervenção manual
    • O texto também trata do fato de que modificar diagramas toma muito tempo. Na prática, é realmente assim, e seria bom poder seguir corretamente um esquema padronizado e ter a ferramenta oferecendo opções de formatação automática
    • Quando você move elementos e realinha tudo, precisa reaprender o diagrama inteiro. Se o frobnitz sempre ficava no canto superior direito e de repente é movido para o meio à esquerda porque o alinhamento fica melhor, isso pode ajudar alguém que está vendo pela primeira vez, mas para quem olhou para aquilo por seis meses parece uma coisa completamente diferente
      É parecido com uma UI feia. Mesmo sendo feia, os usuários já estão acostumados. No momento em que você “organiza”, acaba quebrando o modelo mental deles e os obriga a reaprender
    • Se esse investimento de tempo vale a pena depende do alcance e da vida útil do diagrama
      Às vezes é só um esboço para organizar ideias que será descartado 20 minutos depois
      Mas, se for uma referência para onboarding ou para explicar o sistema a outras equipes, uma hora gasta para criar algo mais fácil de entender pode se pagar muito bem

  • Uso yEd para desenhar esse tipo de coisa. Mesmo que eu faça uma bagunça com caixas e setas, alguns cliques no menu reorganizam tudo automaticamente
    Mas é preciso aceitar alguns compromissos. Caixas dentro de caixas nem sempre terminam bem. Ainda assim, permite documentar muito mais rápido e, depois de tentar algumas vezes, você pega o jeito do que funciona e do que não funciona, então para mim é um bom meio-termo

    • Fico me perguntando se o yEd pode ser usado gratuitamente. O yWorks SDK, no qual ele se baseia, parece custar um valor de cinco dígitos até para um único desenvolvedor em um único site. Se eles têm clientes há quase 20 anos, deve ser uma ferramenta bem poderosa
    • Uso do mesmo jeito. Não há motivo para desenhar manualmente
      Basta extrair as relações em TGF, importar e aplicar um layout hierárquico
      O formato from, to, relation é suficiente
    • Uso OmniGraffle por motivos parecidos

  • Há aqui uma forte semelhança com esquemas elétricos, diagramas de circuitos e outros desenhos de engenharia. Não existe uma única forma “correta”
    Assim como no código, a capacidade de escolher boas abstrações e formas de representação separa uma ideia compreensível de uma bagunça lamentável. Não é uma questão de beleza ou estética, mas uma ferramenta que exige pensamento e esforço ativos no projeto

    • Manter o nível de abstração consistente às vezes é realmente difícil. Especialmente em diagramas de infraestrutura, é difícil conter a vontade de colocar detalhes de níveis diferentes
      Seria bom ter uma ferramenta que permitisse dar zoom para dentro do diagrama com facilidade, como uma animação de zoom infinito

  • Em breve, vamos lançar o v1.0 de https://VisualFlows.io
    Consegui criar em poucos minutos um mapa “arquitetural” animado do SaaS da empresa-mãe: https://app.visualsitemaps.com/user_flows/share/e64da8ed-2ef...
    Os principais recursos são Smart Sections, Smart Edges, Smart Node Deletion, modos claro/escuro, embeds, arrastar e soltar imagens/SVG/GIF, ícones da AWS/Windows/Google, Markdown previsto para a próxima semana etc.
    Sobre Smart Sections: https://support.visualsitemaps.com/en/articles/6477269-how-t...

    • Fico curioso para saber por que eu deveria usar isso em vez do https://whimsical.com, que é mais maduro e tem a mesma estética

  • Gostei muito deste texto. Seja desenhando diagramas de arquitetura, escrevendo documentação ou código, ou fazendo qualquer coisa no trabalho, tento reservar um tempinho para deixar tudo “bonito”
    É difícil explicar por quê, mas sei que gosto mais quando vejo o resultado
    Eu me preocupava um pouco que talvez essa não fosse a melhor forma de usar o tempo, mas nunca ouvi ninguém dizer para não fazer isso
    O motivo de eu gostar deste texto é que ele explica aquilo que eu fazia por intuição como métodos práticos para tornar algo mais bonito

    • Eu também faço isso. Programar é uma atividade bastante visual para mim. Só consigo descrever como um “fluxo”. Se o código não tem fluxo, não fico satisfeito
      Fico perplexo quando vejo colegas de equipe que parecem não ter senso visual para código. Não colocam espaço entre o fim de uma função e a declaração da próxima, ou alternam entre colocar um parâmetro por linha na assinatura de uma função e colocar vários por linha. Para mim isso salta aos olhos, mas eles parecem não se importar
    • Mesmo que eu não compartilhe com ninguém, o próprio processo de pensar na ordem dos blocos e elementos na página me faz refletir sobre a estrutura maior e as dependências. Ajuda demais
    • Tenho a mesma sensação ao criar diagramas de rede no Visio. Entro no modo Steve Jobs e fico obcecado por pequenos detalhes
      Às vezes leva tempo, mas dá uma sensação de preenchimento. Sei que tenho algum talento artístico técnico e, no ensino médio, queria ser desenhista técnico
    • É por isso que existe markup. Ele nos tira da decoração improdutiva. Claro, isso não se aplica à programação
    • “A discussão gira em torno deste diagrama. As pessoas se aproximam casualmente e olham para ele. As perguntas são respondidas apontando para o diagrama. Periodicamente, ao longo do dia, as cadeiras se viram para esse objeto central, e as pessoas entrelaçam as mãos atrás da cabeça.”
      É exatamente o objetivo da visualização

  • D2 é bom para esse tipo de uso. Em uma função anterior, escrevi um programa que analisava todos os arquivos serverless.yml e gerava automaticamente um diagrama D2 gigantesco
    Estávamos trabalhando com microsserviços na AWS, e era bom que ele fosse atualizado automaticamente conforme o sistema crescia. Fiz com que pudesse ser dividido em diagramas menores para cada subsistema, por exemplo separando por SNS topic

    • Também gosto do draw.io

  • Não entendi o primeiro exemplo. O autor fala sobre um nó não planejado e, na prática, o nomeia “I was unplanned”, depois diz “se tivesse planejado com antecedência”
    Não sei como seria possível planejar com antecedência algo não planejado no contexto de um diagrama. Fico pensando se isso significa que devemos deixar espaço em branco suficiente ao redor de todos os nós
    Além disso, a melhoria proposta faz parecer que “something” e “I was unplanned” usam o mesmo canal ou mecanismo ao interagir com “engine”

  • Uso Miro e ele é bem decente para conteúdo de alto nível ou ideação com a ferramenta de post-its. Mas não passa de um nível intermediário
    Depois que os componentes e sistemas estão definidos, há ferramentas mais adequadas para esse trabalho

  • Se a documentação do projeto estiver em Markdown, dá para inserir diagramas usando blocos ```plantuml, em vez de binários separados
    No GitLab, eles são renderizados de forma bonita ao visualizar arquivos .md no navegador. O GitHub ainda não tem esse recurso