Cómo dibujar diagramas de arquitectura de software (2022)

 (terrastruct.com)
3 puntos por GN⁺ 2023-10-28 | 1 comentarios | Compartir por WhatsApp
  • Un buen diagrama de arquitectura permite comunicar ideas y sostener la colaboración por mucho tiempo mediante el nivel correcto de abstracción, mantenerse actualizado y eliminar ambigüedades, más que con adornos
  • La base es minimizar la distancia entre vecinos colocando cerca los elementos conectados, y cuanto más crece el diagrama, más necesario se vuelve repetir el proceso de borrar y volver a dibujar
  • La simetría no solo crea una impresión visual agradable, sino que también refuerza el significado al ubicar, por ejemplo, las entradas de un lado y las salidas del otro
  • Mantener la alineación centrada de las figuras hace que incluso los conceptos complejos parezcan menos complejos y evita que la disposición general se desordene al agregar nuevos elementos
  • Los grupos contenedores con etiquetas permiten mostrar de un vistazo la separación de entornos como AWS y Azure, abstracciones como implementaciones de ReaderWriter, y conjuntos de objetos relacionados como Cores

Condiciones para un diagrama que perdura

  • Un buen diagrama no se borra cuando termina la reunión, sino que puede seguir usándose como punto de referencia para discusiones y preguntas posteriores
  • Los diagramas que se usan por mucho tiempo tienen varias condiciones en común
    • Los elementos deben estar en el nivel correcto de abstracción
    • Deben mantenerse actualizados
    • No debe haber ambigüedad
  • La misma entidad y sus relaciones pueden dibujarse de muchas maneras, pero algunas disposiciones ayudan a la colaboración durante todo el proyecto y otras desaparecen al terminar la reunión
  • La belleza de la que se habla aquí no es decoración como sombras o esquinas redondeadas, sino una belleza funcional que transmite las ideas con eficacia

Principios para crear una disposición fácil de leer

  • Minimizar la distancia entre vecinos

    • La regla básica es dibujar cerca los nodos que están conectados entre sí
    • En diagramas pequeños es fácil, pero a medida que el diagrama crece y se agregan nuevas conexiones, esta propiedad tiende a romperse
    • Así como en el código se corrigen las partes relacionadas cuando se encuentra un caso límite, o se ajusta una oración cuando falta algo en un documento, los diagramas para documentación también deben borrarse y redibujarse cuando haga falta
    • En una entrevista, el costo de volver a dibujar puede ser una carga, pero si es un documento que usarán varias personas o varios equipos, iterar lleva a un mejor diagrama

  • Buscar simetría

    • La simetría contribuye mucho a la impresión estética del diagrama, y el cerebro humano tiende a preferir la simetría visual, como sucede con los rostros
    • Aunque todos los nodos estén lo más cerca posible de sus vecinos, si falta simetría puede verse como un dibujo ligeramente torcido
    • Incluso si la distancia a los vecinos de algún nodo aumenta un poco, la versión simétrica puede verse mejor
    • Colocar las entradas de un lado y las salidas del otro refuerza tanto la simetría como el significado del diagrama

  • Alineación centrada

    • La alineación es un factor importante para que un diagrama se vea ordenado
    • Un diagrama ordenado hace que el concepto se vea más claro, mientras que uno desordenado hace que el concepto parezca más complejo
    • Si desde el inicio se colocan figuras al azar en un lienzo vacío, es fácil que la disposición posterior también siga siendo aleatoria
    • La alineación solo tiene sentido entre dos o más figuras, así que si se mantiene cada vez que se agrega un nuevo elemento, el diagrama se vuelve naturalmente más ordenado
    • Muchas veces la alineación surge a partir de la simetría, pero no siempre

  • Usar grupos contenedores

    • Si divides el diagrama en varias áreas etiquetadas, a quien lo vea le resultará más fácil entender la estructura
    • Los contenedores pueden agregar la siguiente información al diagrama
      • Añaden contexto, como en “estos servicios están en AWS y estos servicios están en Azure”
      • Muestran abstracción, como en “todos estos son implementaciones de ReaderWriter”
      • Agrupan objetos relacionados, como cuando core 1, 2, 3 y 4 se reúnen dentro del contenedor “Cores”

Temas que continúan en la siguiente parte

  • En la Parte 2 continúan los siguientes temas
    • Trazado de rutas de aristas
    • Tamaño y posición de etiquetas
    • Color
    • Íconos

Lecturas relacionadas

1 comentarios

 
GN⁺ 2023-10-28
Comentarios en Hacker News

  • Me gusta mucho hacer diagramas con D2. Es parecido a mermaid.js, pero tiene más opciones de formato y, personalmente, creo que la sintaxis también es mejor
    También escribí un texto corto sobre eso: https://victorbjorklund.com/build-diagrams-as-code-with-d2-d...

    • Siento que los diagramas no deberían ser bonitos. Por ejemplo, el color no debería usarse como una decisión estética o artística, sino para transmitir significado
      Sé que un diagrama de software feo no es agradable de ver, pero decorarlo es parecido a poner curvas en una gráfica de líneas. Se ve mejor visualmente, pero interfiere con los datos que se quieren comunicar
    • Probé seguir el ejemplo y estuvo realmente genial, pero, a diferencia de lo que decía la guía, se renderizó de arriba hacia abajo y no de izquierda a derecha
      Rendericé el primer ejemplo x -> y a SVG, luego abrí solo el SVG en el navegador, y busqué por todo el documento cómo alinear la salida, pero no lo encontré
      Dejé de usarlo porque la documentación y el resultado real no coincidían. Busqué "d2lang connection left to right" y llegué a https://d2lang.com/tour/layouts/; no parece estar enlazado desde la documentación general, así que incluirlo podría ayudar a los visitantes
    • https://flowchart.fun/ me ayudó a hacer flujogramas muy rápido para entender procesos del sistema. Lo mejor fue lo intuitivo que es y lo rápido que permite iterar; además, el CSS personalizado para estilos fue bastante útil
      Al menos para flujogramas, me parece de las herramientas de diagramas basadas en texto más fáciles y rápidas que he usado hasta ahora
    • D2 tiene un muy buen motor de layout, tala, pero necesitas una licencia de pago para usarlo. Los otros dos motores no son tan buenos
    • Me gusta mermaid y lo uso seguido, pero también debería revisar D2. Los diagramas declarativos me parecen una herramienta poderosa para capturar ideas en una forma fácil de leer y poder versionarlas como cualquier otro texto

  • Cuando un sistema empieza a cambiar, los diagramas bonitos se vuelven muy difíciles de mantener. Piensa en agregar una caja nueva en medio de un diagrama ya complejo; podrías tardar una hora en reacomodar todo
    En los años 2020, probablemente el tiempo de un desarrollador se aprovecha mejor gestionando diagramas como código: https://www.ilograph.com/blog/posts/its-time-to-drop-drag-an...

    • Siempre bromeo con que 10% del trabajo de hacer diagramas es crear el diagrama en sí, y 90% es alinear flechas
      Pero la verdad es que ya no parece broma
    • Mantuve un modelo C4 para importarlo y mostrarlo en structurizr.com, y sinceramente no fue agradable. El código por sí solo no daba la comprensión intuitiva ni la vista general que obtienes con un diagrama, y tampoco había una vista previa local rápida, así que había que subir el código al servidor
      Lo peor era que al agregar una caja nueva normalmente había que volver a alinear todas las flechas. Como resultado, el diagrama no lograba mantenerse actualizado de forma continua
      Para diagramas de secuencia me fue mejor usando plantML. El trabajo en sí era más sencillo, así que la salida del intérprete normalmente quedaba usable sin mucha intervención manual
    • El artículo también habla del tiempo que toma modificar diagramas. De verdad es así, y estaría bien que hubiera una herramienta que permitiera seguir correctamente un esquema estandarizado y ofreciera opciones de formato automático
    • Cuando te la pasas moviendo y reordenando elementos, terminas teniendo que aprenderte de nuevo todo el diagrama. Si frobnitz siempre estuvo arriba a la derecha y de pronto lo mueven al centro izquierdo porque “queda mejor” en la distribución, quizá ayude a alguien que lo ve por primera vez, pero para quien lo ha visto durante 6 meses parece una cosa completamente distinta
      Es parecido a una UI fea. Aunque sea fea, quienes la usan ya están acostumbrados. En el momento en que la “ordenas”, rompes su modelo mental y los obligas a reaprenderla
    • Que esa inversión de tiempo valga la pena depende del alcance y la vida útil del diagrama
      A veces solo estás haciendo un boceto para ordenar ideas y lo vas a tirar 20 minutos después
      Pero si es material de referencia para onboarding o para explicarle el sistema a otro equipo, una hora invertida en hacerlo más fácil de entender puede compensarse de sobra

  • Para dibujar estas cosas uso yEd. Aunque deje cajas y flechas hechas un desastre, con unos cuantos clics en el menú las ordena automáticamente
    Claro, hay que aceptar ciertas concesiones. Las cajas dentro de cajas no siempre terminan bien. Aun así, puedo documentar mucho más rápido, y después de hacerlo varias veces ya agarras intuición de qué funciona y qué no, así que para mí es un buen compromiso

    • Me pregunto si yEd puede usarse gratis. Parece que el yWorks SDK en el que se basa cuesta una suma de cinco cifras incluso para que lo use un solo desarrollador en un solo sitio web. Si han tenido clientes durante casi 20 años, debe ser una herramienta bastante sólida
    • Yo hago exactamente lo mismo. No hay razón para dibujarlo a mano
      Solo extraes las relaciones como TGF, las importas y aplicas un layout jerárquico
      Con el formato from, to, relation basta
    • Por razones parecidas uso OmniGraffle

  • Aquí hay una fuerte similitud con los esquemas eléctricos, diagramas de circuitos y otros planos de ingeniería. No existe una única forma “correcta” de hacerlo
    Igual que en el código, la capacidad de elegir buenas abstracciones y formas de representación es lo que separa una idea comprensible de un desastre del que luego te arrepientes. No es un tema de belleza ni de estética, sino una herramienta que requiere pensamiento activo y esfuerzo en el diseño

    • A veces es realmente difícil mantener consistente el nivel de abstracción. Sobre todo en diagramas de infraestructura, cuesta contener el impulso de meter más detalles de distintos niveles a la vez
      Estaría bueno que existiera una herramienta con la que pudieras acercarte fácilmente dentro del diagrama, como una animación de zoom infinito

  • Pronto lanzarán https://VisualFlows.io v1.0
    Pudieron crear en pocos minutos un mapa animado de “arquitectura” del SaaS de su empresa matriz: https://app.visualsitemaps.com/user_flows/share/e64da8ed-2ef...
    Las funciones principales son Smart Sections, Smart Edges, Smart Node Deletion, modo oscuro/claro, embeds, arrastrar y soltar imágenes/SVG/GIF, íconos de AWS/Windows/Google y Markdown, previsto para la próxima semana
    Referencia sobre Smart Sections: https://support.visualsitemaps.com/en/articles/6477269-how-t...

    • Me pregunto por qué usaría esto en lugar de https://whimsical.com, que ya está más maduro y tiene una estética parecida

  • Este artículo me gustó mucho. Ya sea al hacer diagramas de arquitectura, escribir documentos o código, o hacer cualquier cosa en el trabajo, trato de tomarme un momento para que “se vea bien”
    Me cuesta explicar por qué, pero sé que después me gusta más verlo
    Me preocupaba un poco que quizá no fuera la mejor manera de usar el tiempo, pero nunca he oído a nadie decir que no deba hacerlo
    Lo bueno de este artículo es que explica algo que hacía por intuición como una forma práctica de hacer algo más bello

    • Yo también hago esto. Para mí, programar es un trabajo bastante visual. Solo puedo describirlo como “flujo”. Si el código no tiene flujo, no me deja satisfecho
      Me desconcierta ver compañeros de equipo que parecen no tener ese sentido visual del código. No dejan una línea en blanco entre el final de una función y la declaración de la siguiente, o en la firma de una función a veces ponen un parámetro por línea y otras varias en una sola, de forma inconsistente. A mis ojos resalta muchísimo, pero parece que a ellos no les importa
    • Aunque no se comparta con nadie, el simple proceso de pensar el orden de los bloques y elementos en una página te hace reflexionar sobre la estructura mayor y las dependencias. Ayuda muchísimo
    • Me pasa lo mismo al hacer diagramas de red en Visio. Entro en modo Steve Jobs y me obsesiono con los pequeños detalles
      A veces toma tiempo, pero se siente como si llenara algo dentro de mí. Sé que tengo cierto talento técnico-artístico, y en la preparatoria quería ser dibujante técnico
    • Para eso existe el marcado. Te saca de la decoración improductiva. Claro, eso no aplica a programar
    • “La discusión gira alrededor de este diagrama. La gente se acerca sin pensarlo y se queda mirándolo. Las preguntas se responden señalando el diagrama. A intervalos durante el día, las sillas se giran hacia esta pieza central y la gente entrelaza las manos detrás de la cabeza.”
      Ese es exactamente el objetivo de la visualización

  • D2 sirve bien para este tipo de uso. En un puesto anterior escribí un programa que analizaba todos los archivos serverless.yml y generaba automáticamente un enorme diagrama D2
    Estábamos haciendo microservicios en AWS, y era bueno que se actualizara automáticamente a medida que el sistema crecía. Lo hice de forma que pudiera dividirse en diagramas más pequeños por subsistema, separándolos según el topic de SNS

    • También me gusta draw.io

  • No entiendo el primer ejemplo. El autor habla de un nodo no planeado, le pone literalmente el nombre “I was unplanned”, y luego dice “si lo hubieras planeado de antemano”
    No entiendo cómo se puede planear por adelantado algo no planeado en el contexto de un diagrama. Me pregunto si lo que quiere decir es que hay que dejar suficiente espacio en blanco alrededor de todos los nodos
    Además, la mejora propuesta hace que “something” y “I was unplanned” parezcan usar el mismo canal o mecanismo al interactuar con “engine”

  • Uso Miro, y para contenido de alto nivel o ideación funciona bastante bien con la herramienta de post-its. Pero no pasa del nivel intermedio
    Una vez definidos los componentes y sistemas, hay herramientas más adecuadas para ese trabajo

  • Si la documentación del proyecto está en Markdown, puedes insertar diagramas poniendo un bloque ```plantuml en lugar de un binario aparte
    En GitLab se renderiza bien cuando ves el archivo .md en el navegador. GitHub todavía no tiene esa función