Por qué los diagramas basados en texto merecen un lugar en tu flujo de trabajo de Confluence

Escribir un diagrama en código puede parecer contraintuitivo, pero para los equipos a los que les importan el mantenimiento, la coherencia y la velocidad, puede transformar la forma en que el conocimiento vive dentro de Confluence.

Ilustración de una página de Confluence con un diagrama de flujo que parte de un recuadro tachado hacia dos cuadros de texto y tres círculos verdes

Por qué los diagramas basados en texto merecen un lugar en tu flujo de trabajo de Confluence

La mayoría de los equipos empiezan con los diagramas de la misma manera: arrastrando formas a un lienzo y conectándolas con flechas. Es intuitivo, visual y familiar. Pero, a medida que la documentación crece entre equipos de ingeniería, revisiones de arquitectura y proyectos multifuncionales, otro enfoque empieza a destacar: los diagramas basados en texto. Escribir un diagrama en código puede parecer contraintuitivo, pero para los equipos a los que les importan el mantenimiento, la coherencia y la velocidad, puede transformar la forma en que el conocimiento vive dentro de Confluence.

Capable Diagrams admite más de 23 formatos de diagrama, y muchos de los más potentes (Mermaid, PlantUML, C4, DBML, D2, GraphViz y otros) se basan en texto. Eso significa que tus diagramas se definen en texto plano, se renderizan automáticamente y se guardan en un formato fácil de revisar, actualizar y reproducir. Para los equipos que ya trabajan en Confluence, esto abre la puerta a un flujo de trabajo más rápido, más colaborativo y mucho menos frágil que los métodos tradicionales de arrastrar y soltar.

El problema de los diagramas perfectos al píxel

Los diagramas que se crean primero de forma visual tienen un coste oculto. Cuando un diagrama se construye totalmente a mano (cada caja colocada, cada línea trazada, cada etiqueta posicionada), resulta difícil de actualizar. Alguien cambia el nombre de un servicio o añade una nueva dependencia y, de repente, el diagrama necesita una reorganización cuidadosa para no quedar recargado. Con el tiempo, estos diagramas se quedan desactualizados porque el esfuerzo de mantenerlos supera el valor que se les atribuye.

Esto ocurre sobre todo en equipos de ingeniería que avanzan rápido. La arquitectura evoluciona sprint a sprint. Los modelos de datos ganan campos nuevos. Los pipelines de despliegue añaden etapas. Si actualizar un diagrama lleva diez minutos de arrastrar y alinear con cuidado, no se actualizará. El diagrama se convierte en decoración en lugar de documentación: algo que la gente mira de pasada, pero en lo que ya no confía.

Cómo cambian las reglas del juego los diagramas basados en texto

Con los diagramas basados en texto de Capable Diagrams, describes lo que contiene un diagrama en lugar de cómo se ve. Un diagrama de secuencia de Mermaid, por ejemplo, son solo unas pocas líneas que describen los participantes y sus interacciones. Un modelo C4 define sistemas, contenedores y componentes en texto estructurado. El motor de renderizado se encarga automáticamente de la disposición, el espaciado y el estilo.

Esto tiene varias ventajas prácticas para los equipos de Confluence. En primer lugar, las actualizaciones son rápidas. Cambiar una etiqueta o añadir un nodo nuevo lleva segundos: editas una línea de texto y el diagrama se vuelve a renderizar. No hace falta recolocar nada. En segundo lugar, el código fuente del diagrama es legible. Cualquiera que revise una página de Confluence puede entender la estructura de un diagrama de flujo de Mermaid con solo leer su definición, incluso sin el resultado visual. En tercer lugar, los diagramas basados en texto se pueden comparar por naturaleza. Cuando consultas el historial de versiones en Confluence, puedes ver exactamente qué cambió en la definición del diagrama, no solo que «la imagen se ve distinta».

Para los equipos que usan Capable Diagrams dentro de Confluence, pasar de la edición visual a la basada en texto es totalmente fluido. Puedes empezar con un editor visual al estilo de Excalidraw para las primeras lluvias de ideas y pasar después a Mermaid o PlantUML cuando el diagrama tenga que ser preciso y fácil de mantener. Ambos enfoques conviven en la misma macro, en la misma página y con el mismo historial de versiones.

Un diagrama de casos de uso de PlantUML

Un diagrama de casos de uso de PlantUML

Elegir el lenguaje adecuado para cada tarea

Uno de los puntos fuertes de Capable Diagrams es que no te limita a una única sintaxis. Cada lenguaje de diagramas sirve para un propósito distinto, y elegir el adecuado hace que tu documentación sea más clara sin esfuerzo adicional.

Mermaid es una excelente opción por defecto para la mayoría de los equipos. Permite crear diagramas de flujo, diagramas de secuencia, diagramas de Gantt, diagramas de clases y diagramas de estados con una sintaxis fácil de aprender. Si estás documentando un flujo de trabajo de usuario o una interacción con una API, Mermaid te lleva de la idea al diagrama publicado en minutos. PlantUML es una gran elección para un trabajo UML más detallado: jerarquías de clases, diagramas de actividad y vistas de despliegue en las que necesitas un control más preciso de la notación. Para la documentación de arquitectura, los diagramas C4 ofrecen una forma estructurada de describir sistemas en varios niveles de abstracción, desde una vista de contexto general hasta los componentes individuales.

Para los equipos de bases de datos, la compatibilidad con DBML y ERD te permite definir las relaciones de tu esquema directamente en Confluence, de modo que la documentación del modelo de datos está junto al resto del conocimiento del proyecto. D2 y GraphViz ofrecen opciones potentes para disposiciones de grafos personalizadas cuando los tipos de diagrama estándar no encajan del todo. No se trata de aprender los 23 formatos, sino de saber que existe la herramienta adecuada cuando la necesitas y que Capable Diagrams la renderizará de forma nativa en tu página de Confluence.

Todos los tipos de diagrama que necesitas, en Confluence.

Todos los tipos de diagrama que necesitas, en Confluence.

Un ejemplo práctico: registros de decisiones de arquitectura

Piensa en un caso habitual. Tu equipo mantiene registros de decisiones de arquitectura (ADR) en Confluence: páginas que recogen por qué se tomó una determinada decisión técnica. Estas páginas suelen incluir un diagrama que muestra el contexto del sistema o los componentes afectados por la decisión.

Con los diagramas basados en texto, el diagrama forma parte del contenido de la página de una manera fácil de copiar, modificar y ampliar. Cuando un futuro miembro del equipo vuelva al ADR y la arquitectura haya evolucionado, podrá actualizar el diagrama en segundos editando la definición de texto. No necesita encontrar al autor original, localizar un archivo fuente ni deducir cómo se organizaron las formas. El diagrama es autónomo, cualquiera puede editarlo y siempre está sincronizado con el texto que lo rodea.

Este flujo de trabajo es aún más potente si lo combinas con otras herramientas de Capable. Puedes usar Capable Markdown para escribir el propio ADR en Markdown, insertar un diagrama de Mermaid en línea y, después, enviar la página a Capable Approvals para su aprobación. Todo el registro de la decisión (texto, diagrama y estado de aprobación) está en una sola página de Confluence, sin dependencias externas.

Diagrama de ADR en Mermaid

Diagrama de ADR en Mermaid

Primeros pasos sin rehacer tu proceso

Adoptar diagramas basados en texto no exige cambiar por completo la forma de trabajar de tu equipo. Un buen punto de partida es elegir un tipo de diagrama recurrente (por ejemplo, diagramas de secuencia para la documentación de API o diagramas de flujo para los flujos de trabajo de incorporación) y probar a escribirlo en Mermaid la próxima vez que haya que actualizarlo. Capable Diagrams incluye sugerencias basadas en IA que te ayudan a empezar con la sintaxis de Mermaid y reducen considerablemente la curva de aprendizaje.

Con el tiempo, probablemente verás que ciertos tipos de diagramas pasan de forma natural a formatos basados en texto porque se actualizan con frecuencia, mientras que otros siguen siendo visuales porque se crean una vez y apenas cambian. Y no pasa nada. El valor de Capable Diagrams es que ambos enfoques conviven en la misma herramienta, en las mismas páginas de Confluence, sin ninguna fricción.

La mejor documentación es la que se mantiene al día. Los diagramas basados en texto facilitan que el contenido visual siga siendo preciso, de modo que tu equipo dedica menos tiempo a rehacer diagramas y más a construir los sistemas que describen.

Capable Diagrams forma parte de la suite de apps de Capable para Confluence Cloud, que ayuda a los equipos a planificar, documentar y colaborar sin salir de las herramientas que ya usan.

Configuración de cookies

Cuidamos de ti y de tus datos. Aquí puedes leer más sobre cómo usamos las cookies y qué terceros las instalan, y actualizar tu configuración de cookies.