Diagramas de arquitectura que no se quedan obsoletos: un flujo de documentación viva

Toda organización de ingeniería tiene uno: el diagrama de arquitectura de la wiki que fue correcto durante unas semanas, hace años. Las personas nuevas lo estudian y luego un compañero les cuenta que la mitad de las cajas cambiaron de nombre y que la cola del centro se reemplazó la primavera pasada. La mayoría de las buenas prácticas de documentación de arquitectura se centran en qué dibujar. Este artículo trata de la parte difícil: mantener los diagramas correctos después del primer borrador, con un flujo de trabajo que los trate como documentación viva y no como entregables de un solo uso.

Por qué la documentación de arquitectura se queda obsoleta

Los diagramas rara vez se quedan obsoletos porque la gente sea perezosa. Se quedan obsoletos porque el proceso que los rodea convierte eso en lo normal.

• Son entregables de un solo uso. Un diagrama se dibuja para una revisión de diseño, el arranque de una migración o una auditoría. En cuanto termina la reunión, nadie tiene motivos para volver a abrirlo.
• Las capturas de pantalla se pegan en todas partes. El archivo fuente vive en el portátil de alguien, y un PNG acaba en la wiki, en el documento de onboarding, en tres presentaciones y en un README. Ahora hay cinco copias y ninguna se puede editar.
• Nadie es su dueño. “El equipo de plataforma” no es un responsable. Cuando nadie en concreto es responsable, todos asumen que otra persona lo actualizará.
• Nada dispara una actualización. Los cambios de código pasan por pull requests, revisión y CI. Los diagramas solo cambian cuando alguien se acuerda, y eso rara vez coincide con el momento en que cambia el sistema.
• Muestran demasiado. Un diagrama con cada Pod, cada cola, cada rol de IAM y cada recorrido de usuario está desactualizado el mismo día en que se termina, porque cualquier cambio en cualquier parte lo vuelve incorrecto.

Ninguno de estos es, ante todo, un problema de herramientas; una herramienta de dibujo mejor no sustituye a un responsable que falta. Pero la herramienta puede hacer que el flujo correcto sea barato o caro.

Buenas prácticas de documentación de arquitectura para diagramas vivos

Este es el flujo que recomendamos. Toma partido a propósito.

1. Una fuente de verdad por diagrama

Cada diagrama existe en un único lugar editable. Todo lo demás es un enlace o un embed que apunta a ese lugar. Si estás a punto de exportar un PNG para pegarlo en algún sitio, pregúntate si bastaría con un enlace. Casi siempre basta.

2. Enlaza, no copies

Las wikis, los sitios de documentación y los README deben apuntar al diagrama vivo, no contener una imagen de él. Un diagrama incrustado en vivo cambia cuando cambia la fuente; una captura pegada es incorrecta para siempre después del siguiente cambio. Cuando de verdad necesites una imagen estática, como un PDF para un auditor, trátala como una exportación fechada y mantenla fuera de la documentación que la gente usa a diario.

3. Nombra un responsable

Cada diagrama tiene un responsable: una persona o un equipo con un punto de contacto con nombre. El responsable no dibuja cada cambio, pero es quien se da cuenta cuando algo está mal y a quien se le pregunta. Pon el responsable en el propio diagrama y en tu índice de diagramas.

4. Conecta las actualizaciones a eventos que ya existen

No dependas de la memoria. Vincula las actualizaciones de diagramas a eventos que ya ocurren:

• Pull requests. Añade a la plantilla de PR una casilla de impacto en la arquitectura.
• ADR. Cada architecture decision record aceptado enlaza el diagrama que modifica, y el diagrama se actualiza como parte de su aprobación.
• Postmortems de incidentes. Si el incidente mostró que el diagrama era incorrecto o le faltaba una dependencia, corregirlo pasa a ser una acción pendiente.
• Revisión trimestral. Los responsables dedican unos minutos a cada diagrama para confirmar que sigue reflejando la realidad y actualizan la fecha de “última revisión”.

Un fragmento de plantilla de PR:

## Architecture impact
- [ ] This change does not affect any architecture diagram
- [ ] I updated the affected diagram(s) and linked them below
- [ ] This needs an ADR (link):

5. Elige el nivel de detalle adecuado

Usa niveles en lugar de una única imagen gigante. El C4 model te da un vocabulario común: una vista System Context (personas y sistemas), una vista Container (aplicaciones y almacenes de datos) y una vista Component dentro de un container. Los niveles altos cambian poco y son baratos de mantener al día. Los niveles bajos cambian a menudo, así que dibújalos solo donde la gente los necesite y deja que, por debajo de eso, el código sea la fuente de verdad.

Una regla útil: si un diagrama cambia en cada sprint, probablemente está dibujado un nivel demasiado profundo.

6. Haz visibles la fecha y la versión

Pon el responsable y una fecha de “última revisión” en una esquina de cada diagrama. Así quien lo lea puede juzgar de un vistazo cuánto confiar: un diagrama revisado el mes pasado y otro revisado hace dos años merecen niveles de confianza distintos. Sin fecha, todos los diagramas parecen igual de fiables, y eso es peor que mostrar una fecha antigua.

7. Mantén un índice de diagramas

Una página lista todos los diagramas que importan:

El índice hace visibles los huecos (sin responsable, fecha antigua) y es el punto de partida natural para la revisión trimestral.

8. Combina diagramas con ADR

Un diagrama muestra qué es la arquitectura. No puede mostrar por qué. Los architecture decision records cubren ese hueco. El formato ADR original de Michael Nygard es lo bastante corto como para que la gente realmente los escriba: título, estado, contexto, decisión, consecuencias. Enlaza el ADR desde el diagrama y el diagrama desde el ADR:

# ADR-019: Move payment events to a dedicated queue

## Status
Accepted

## Context
Payment events share a queue with notifications.

## Decision
Give payment events their own queue.

## Consequences
One more queue to operate. Diagram "Payments: containers" updated.

Cuando alguien pregunte dentro de seis meses “¿por qué está así?”, la respuesta estará a un clic.

Cómo Archboard apoya un flujo de documentación viva

Archboard es un espacio de trabajo de arquitectura alojado en la nube, y la mayor parte del flujo anterior se corresponde con funciones que ya tiene. Esto es lo que cubre y dónde sigues necesitando tu propio proceso.

• Una fuente de verdad. Cada diagrama es un único documento en tu workspace, con guardado automático y snapshots de revisión. Free conserva las últimas 5 revisiones; Pro guarda un año de historial de revisiones y Enterprise no tiene límite.
• Enlaza, no copies. Todos los planes tienen enlaces públicos para compartir (con marca en Free). En Pro y Enterprise puedes incrustar un diagrama en tu sitio de documentación mediante iframe, para que la página muestre la versión actual en lugar de una captura que se desactualiza.
• Historial en tu repositorio. Exporta el diagrama como JSON estructurado y haz commit junto al código o a tus ADR. Así tienes historial en Git y un paso de revisión para los cambios de diagramas, además de las revisiones dentro de la app. La exportación es un paso manual, así que conviértela en parte de tu rutina de PR.
• Notas en el canvas. Los nodos Markdown viven en el canvas, de modo que el responsable, la fecha de última revisión, los enlaces a ADR y una leyenda breve están dentro del diagrama y no en un documento aparte.
• El nivel de detalle adecuado. El pack C4 Model incluye los nodos Person, Software System, Container, Component y Database, además de boundaries. Los nodos son nodos de primera clase con puertos, y los unes conectando sus puertos. Mantén las vistas context y container como diagramas separados.

Una configuración concreta para un sistema:

1. Crea dos diagramas: “Payments: Context” y “Payments: Containers”.
2. Añade en la esquina superior izquierda un nodo Markdown con el responsable, la fecha de última revisión y enlaces a los ADR relacionados.
3. En Pro, incrusta la vista container en la página de documentación del servicio. En Free, usa el enlace para compartir.
4. Cuando un PR cambie la arquitectura, actualiza el diagrama (o deja que el agente de programación que trabaja en el PR lo haga a través del servidor MCP de Archboard), exporta el JSON y haz commit en docs/architecture/ dentro del mismo PR.
5. Añade ambos diagramas a tu página de índice.

Consulta la visión general del producto para ver todas las funciones, el caso de uso C4 para configuraciones específicas de C4 y los precios para saber qué incluye cada plan. Free te da 3 diagramas, cada uno con 15 nodos de diagrama más 150 notas, textos, pegatinas y temas de mapa mental, para probar una vista de contexto de un sistema; Pro desbloquea diagramas y nodos ilimitados cuando documentas toda la plataforma.

Checklist de documentación viva

• Cada diagrama tiene exactamente una fuente editable
• La documentación incrusta o enlaza el diagrama vivo, sin capturas pegadas
• Cada diagrama tiene un responsable con nombre, visible en el diagrama
• La plantilla de PR incluye una casilla de impacto en la arquitectura
• Los ADR aceptados enlazan los diagramas que modifican
• Los postmortems preguntan “¿sigue siendo correcto el diagrama?”
• Los responsables revisan sus diagramas cada trimestre y actualizan la fecha
• Los diagramas están separados por nivel C4, no en una imagen gigante
• Un índice de diagramas lista nivel, responsable, fecha de última revisión y ADR
• La fuente del diagrama (por ejemplo, una exportación JSON) está en el repositorio junto al código

Preguntas frecuentes

¿Cuántos diagramas debería tener un sistema? Empieza con una vista context y una vista container. Añade vistas component solo para las partes sobre las que la gente pregunta con frecuencia. Pocos diagramas correctos valen más que muchos obsoletos.

¿Los diagramas deben vivir en el repositorio o en una herramienta? Edítalos en un solo lugar y guarda el historial donde tu equipo ya revisa los cambios. Con Archboard, editas en el canvas y haces commit de la exportación JSON en Git.

Empieza gratis — un asiento, sin tarjeta de crédito