Módulo 3: Comunicar la arquitectura

7. Evitar el documento de 500 páginas y el diagrama-espagueti

Siguiente →

Descripción

Al terminar esta lección vas a reconocer y evitar los dos grandes fracasos de la comunicación de arquitectura, los que arruinan hasta el trabajo de quien ya domina el C4 y el ADR. El primero es el documento de 500 páginas que nadie lee: documentar de más y comunicar de menos, producir tanto texto que la señal se ahoga en el volumen y el lector se rinde antes de encontrar lo que busca. El segundo es el diagrama-espagueti: la lámina que muestra todo el sistema —containers, componentes, clases, integraciones, colas— de una sola vez, con cien flechas cruzándose, técnicamente completa y humanamente ilegible. Los dos fracasos comparten una raíz: confunden completitud con comunicación. Creen que mostrar más es comunicar más. Es al revés: pasado cierto punto, cada elemento de más resta comprensión, porque tapa la idea principal. Esta lección es la vacuna, y trae dos reglas que se pueden medir: un diagrama no debe mezclar niveles de abstracción, y no debe exceder el límite de elementos que la cabeza humana puede leer.

Esto importa porque estos dos fracasos son la forma por defecto en que la documentación de arquitectura sale mal —no por falta de esfuerzo, sino por exceso mal dirigido—. El documento de 500 páginas casi siempre lo escribió alguien aplicado que quería ser exhaustivo; el diagrama-espagueti casi siempre lo dibujó alguien que sabía mucho del sistema y quiso mostrarlo todo. La buena intención no salva el resultado: nadie lee el documento, nadie entiende el diagrama, y el equipo concluye erróneamente que "documentar no sirve". Sí sirve —lo que no sirve es documentar de más—. Y hay un tercer fracaso, más silencioso, que cierra la lección: el diagrama que se pudre porque vive en una wiki separada del código, y describe con precisión un sistema que ya no existe. Un diagrama que miente es peor que ninguno.

Conexión con el módulo: en las lecciones 2 a 5 aprendiste a producir buenos diagramas al nivel correcto; en la 6, buenos ADRs. Esta lección enseña lo complementario: reconocer y evitar la comunicación mala, que a menudo se produce con más trabajo que la buena. Las reglas que vas a medir aquí —un diagrama, un nivel; un diagrama, pocos elementos— son la defensa concreta de todo lo anterior. Y el principio de que la documentación debe vivir versionada con el código (docs-as-code) es lo que mantiene vivo todo lo que produjiste. En la lección 8, el proyecto, vas a correr estos validadores sobre tus propios entregables antes de darlos por buenos.

El mapa que dibuja todas las calles, todos los cables y todas las tuberías

Vuelve a los mapas, pero imagina uno hecho por alguien obsesionado con no omitir nada. En una sola lámina dibuja: las calles, sí, pero también las líneas del metro, y encima las tuberías de agua, y encima los cables eléctricos, y encima las rutas de autobús, y los nombres de cada negocio, y las curvas de nivel del terreno, y las fronteras de cada distrito, todo con el mismo grosor de línea, todo en la misma hoja. ¿Es completo? Absolutamente —está toda la información de la ciudad ahí—. ¿Sirve para algo? Para nada. Nadie puede encontrar una calle en esa maraña, porque la calle que busca está enterrada bajo diez capas de otra cosa. La completitud lo volvió inútil. Un mapa comunica porque omite: el mapa del metro es útil precisamente porque no dibuja las tuberías.

Ahora imagina la versión en texto: el manual de instrucciones de 500 páginas que viene con un electrodoméstico y que documenta cada tornillo, cada norma de seguridad de cada país, cada modo que el aparato nunca usará. Es exhaustivo. Y por eso nadie lo lee: cuando quieres saber cómo encender el aparato, la instrucción está en la página 237, entre la advertencia sobre el uso a gran altitud y la tabla de repuestos para el modelo de 1998. El manual que sí lees es la tarjeta de "inicio rápido": una página, cinco pasos, lo que el 95% de la gente necesita. No es menos honesta —es más útil, porque comunica en vez de archivar—.

El diagrama-espagueti es el mapa de todas las capas; el documento de 500 páginas es el manual completo. Los dos pecan de lo mismo: creen que su trabajo es contenerlo todo, cuando su trabajo es comunicar algo a alguien. Y comunicar exige omitir: elegir el nivel (un mapa, una capa), elegir lo esencial (una página, cinco pasos). El arquitecto que aprende esto deja de medir su documentación por lo completa que es y empieza a medirla por lo que la gente entendió y usó. Vamos a volver medibles las dos reglas que lo evitan.

Las dos reglas de higiene, ejecutadas

Los dos fracasos de diagrama se pueden detectar automáticamente, porque tienen firmas concretas. El espagueti tiene demasiados elementos. El diagrama confuso mezcla niveles de abstracción que no deberían convivir. El siguiente código valida dos diagramas de Mercado contra esas dos reglas: uno bien hecho (el Container que dibujaste en la lección 3) y uno que "muestra todo" (containers + componentes + clases en una sola lámina). Para cada uno reporta si mezcla niveles, si es espagueti, y el veredicto.

# Dos reglas de higiene de diagramas, ejecutadas de verdad.
# Regla 1: un diagrama no debe MEZCLAR niveles de abstraccion.
# Regla 2: un diagrama no debe exceder el limite legible (diagrama-espagueti).

# A que "rango" de abstraccion pertenece cada tipo de elemento del C4.
# person y external_system son CONTEXTO: se permiten como decorado en cualquier nivel.
# Los tipos "internos" son los que definen el nivel del diagrama.
CORE_RANK = {
    "container": 2,
    "component": 3,
    "class": 4,
    "method": 4,
}
CONTEXT_TYPES = {"person", "external_system", "software_system"}

# Umbral de legibilidad: mas alla de esto, el diagrama deja de comunicar.
LEGIBLE_LIMIT = 20  # elementos por diagrama (regla de dedo del C4)

RANK_NAME = {2: "Container", 3: "Component", 4: "Code"}


def check_mixing(elements):
    core_ranks = sorted({CORE_RANK[e["type"]] for e in elements if e["type"] in CORE_RANK})
    levels = [RANK_NAME[r] for r in core_ranks]
    mixed = len(core_ranks) > 1
    return mixed, levels


def check_spaghetti(elements, relationships):
    n = len(elements)
    r = len(relationships)
    too_big = n > LEGIBLE_LIMIT
    return too_big, n, r


def audit(name, elements, relationships):
    print(f"== {name} ==")
    mixed, levels = check_mixing(elements)
    too_big, n, r = check_spaghetti(elements, relationships)
    if mixed:
        print(f"  MEZCLA NIVELES:  si  -> combina {' + '.join(levels)} en un solo diagrama")
    else:
        nivel = levels[0] if levels else "solo contexto"
        print(f"  MEZCLA NIVELES:  no  -> un solo nivel interno ({nivel})")
    if too_big:
        print(f"  ESPAGUETI:       si  -> {n} elementos > limite {LEGIBLE_LIMIT}; {r} flechas: ilegible")
    else:
        print(f"  ESPAGUETI:       no  -> {n} elementos <= limite {LEGIBLE_LIMIT}; {r} flechas: legible")
    verdict = "RECHAZADO" if (mixed or too_big) else "OK, comunica"
    print(f"  VEREDICTO:       {verdict}")
    print()


# Diagrama 1: el Container de Mercado, bien hecho.
container_good_elems = [
    {"type": "person", "name": "Customer"},
    {"type": "person", "name": "Seller"},
    {"type": "container", "name": "Web App"},
    {"type": "container", "name": "Mobile App"},
    {"type": "container", "name": "API"},
    {"type": "container", "name": "Database"},
    {"type": "container", "name": "Search Index"},
    {"type": "external_system", "name": "Payment Gateway"},
    {"type": "external_system", "name": "Carrier API"},
]
container_good_rels = [
    ("Customer", "Web App"), ("Customer", "Mobile App"), ("Seller", "Web App"),
    ("Web App", "API"), ("Mobile App", "API"),
    ("API", "Database"), ("API", "Search Index"),
    ("API", "Payment Gateway"), ("API", "Carrier API"),
]

# Diagrama 2: el diagrama "que muestra TODO" - containers + componentes + clases juntos.
everything_bad_elems = (
    container_good_elems
    + [{"type": "component", "name": f"Comp{i}"} for i in range(1, 9)]
    + [{"type": "class", "name": f"Class{i}"} for i in range(1, 8)]
)
everything_bad_rels = [(f"n{i}", f"n{i+1}") for i in range(1, 35)]

audit("Container de Mercado (bien hecho)", container_good_elems, container_good_rels)
audit("Diagrama 'muestra todo' (una sola lamina)", everything_bad_elems, everything_bad_rels)

Qué esperar. Al correrlo:

== Container de Mercado (bien hecho) ==
  MEZCLA NIVELES:  no  -> un solo nivel interno (Container)
  ESPAGUETI:       no  -> 9 elementos <= limite 20; 9 flechas: legible
  VEREDICTO:       OK, comunica

== Diagrama 'muestra todo' (una sola lamina) ==
  MEZCLA NIVELES:  si  -> combina Container + Component + Code en un solo diagrama
  ESPAGUETI:       si  -> 24 elementos > limite 20; 34 flechas: ilegible
  VEREDICTO:       RECHAZADO

Los dos veredictos cuentan la historia. El Container bien hecho pasa las dos reglas: un solo nivel interno (todo son containers), 9 elementos bajo el límite de 20. Comunica. El diagrama "muestra todo" falla las dos a la vez —y no por casualidad, porque los dos fracasos suelen ir juntos—: mezcla tres niveles (containers, componentes y clases en la misma lámina, que es el mapa de la ciudad con las tuberías y los cables encimados) y es espagueti (24 elementos, 34 flechas, muy por encima de lo que un ojo humano sigue). El validador no tiene gusto estético; solo cuenta. Y con solo contar, distingue el diagrama que comunica del que no.

Fíjate en la regla de la mezcla, porque es sutil. El validador no marca las personas ni los sistemas externos como "mezcla" —esos son contexto, decorado permitido en cualquier nivel (un Container legítimamente muestra a los clientes alrededor)—. Lo que marca es mezclar los elementos internos de distintos niveles: containers con componentes con clases. Esa es la firma real del espagueti confuso: no "tiene muchas cajas", sino "tiene cajas de niveles de zoom incompatibles en la misma hoja". Es exactamente el mapa que dibuja las calles y las tuberías: cada capa por separado sería útil; encimadas, ninguna lo es.

Cómo se ven los dos diagramas, lado a lado

El validador cuenta; el ojo confirma. Así se ve el Container bien hecho —legible, un nivel, pocas cajas—:

   Customer ──▶ Web App ──▶ ┌─────┐ ──▶ Database
   Seller   ──▶ Mobile ───▶ │ API │ ──▶ Search Index
                            └─────┘ ──▶ Payment Gateway
                                    ──▶ Carrier API

   9 cajas, un nivel (containers). Sigues cada flecha con el dedo.

Y así se ve, esquematizado, el diagrama-espagueti —todos los niveles encimados, imposible seguir una flecha—:

  Customer─┐  ┌Web─┬─API──Comp1─Class1   Search─Comp5
     Seller┼─▶│    │   │╲   │  ╳  │   ╲    │  ╳   │
  Mobile───┘  └Comp2╲ Class2─Comp3 Class3─Comp6─Class4
     │  ╳  │   │  ╳ ╲│  ╳ │ ╲ │ ╳ │  ╳  │ ╲ │  ╳
  Payment─Comp4─Class5─DB─Comp7─Class6─Carrier─Comp8─Class7
     └──── 24 cajas, 3 niveles, 34 flechas: nadie lee esto ────┘

No hace falta entender el segundo diagrama —ese es el punto—. Tu ojo rebota, no encuentra por dónde empezar, y se rinde. La misma información que en el primero está clara (Customer usa la web, la web llama a la API) aquí está presente pero ilegible, enterrada bajo componentes y clases que pertenecen a otros niveles de zoom. Completo, sí. Comunicativo, no. Toda la habilidad de esta lección es preferir el primero al segundo, aunque el segundo "tenga más información" —porque comunicar no es contener información, es transmitirla a una cabeza humana—.

El tercer fracaso: el diagrama que se pudre

Hay un modo de fallar que ningún validador de contenido atrapa, porque no es sobre el diagrama en sí sino sobre dónde vive. Un diagrama perfecto —bien nivelado, legible— se vuelve dañino si describe un sistema que ya cambió. El diagrama que en 2024 mostraba con precisión los cinco containers de Mercado, hoy miente si el checkout ya se extrajo a un sexto y nadie actualizó el dibujo. Y miente peor que un diagrama malo, porque parece verdad: el dev nuevo lo cree, actúa sobre él, y se estrella contra la realidad. Un diagrama desactualizado tiene autoridad sin veracidad —la peor combinación—.

La causa casi siempre es la misma: el diagrama vive separado del código, en una wiki, en una carpeta de presentaciones, en la nube de alguien. Cuando el código cambia, el código cambia; el diagrama, en su isla, no se entera. Nadie tiene el reflejo de actualizar un archivo que vive en otro sistema, en otro flujo de trabajo. La documentación en una wiki separada se pudre por diseño, no por descuido.

La cura se llama docs-as-code: la documentación —los diagramas y los ADRs— vive en el mismo repositorio que el código, versionada junto a él, y cambia en el mismo commit y la misma revisión que el código que describe. Esto tiene tres efectos que lo cambian todo. Primero, el diagrama se actualiza cuando el código se actualiza, porque están en el mismo cambio y el revisor lo ve. Segundo, el diagrama tiene historia: puedes ver cómo evolucionó la arquitectura commit a commit, igual que el código. Tercero —y por eso las lecciones anteriores insistieron en diagramas pequeños y ADRs que caben en una pantalla, y en generar el Code en vez de dibujarlo—: los artefactos diffables de texto (mermaid, un ADR en Markdown, un diagrama como código) viven bien en un repositorio; un documento binario de 500 páginas o una imagen exportada a mano, no. Todo el módulo empujó hacia artefactos chicos y textuales precisamente para que puedan vivir versionados con el código y no pudrirse. La documentación que sobrevive es la que comparte el destino del código; la que vive aparte, muere aparte. (La guía de documentación del ecosistema profundiza en docs-as-code; aquí basta el principio: versiona la doc con el código, o se pudre.)

Errores comunes

Medir la documentación por su peso (de exhaustividad). Qué pasa: el equipo se enorgullece de un documento de arquitectura de 500 páginas o de un diagrama que "tiene todo el sistema", y confunde ese volumen con calidad. Nadie lo lee ni lo entiende. Por qué pasa: la completitud es visible y medible ("mira cuánto documentamos") mientras que la comunicación efectiva es invisible ("¿alguien entendió?"). Cómo detectarlo: si describes tu documentación por su tamaño ("500 páginas", "un diagrama enorme con todo") en vez de por su efecto ("el onboarding bajó a dos días"), estás midiendo lo equivocado. Cómo corregirlo: mide por uso y comprensión —¿alguien lo consultó para decidir algo esta semana?, ¿el dev nuevo se orientó con esto?—; y recuerda que comunicar exige omitir, así que un artefacto más corto suele comunicar más.

Mezclar niveles "para que se vea la relación" (de conexión). Qué pasa: el arquitecto quiere mostrar cómo una clase concreta se conecta con un sistema externo, y para eso pone la clase (nivel Code) y el sistema externo (nivel Context) en el mismo diagrama junto con containers y componentes —y crea el espagueti—. Por qué pasa: la intención es buena (mostrar una relación real que cruza niveles), pero la ejecución mezcla zooms incompatibles. Cómo detectarlo: el validador de esta lección lo atrapa —si tu diagrama tiene elementos internos de más de un rango (container + component + class), mezclaste—. Cómo corregirlo: si necesitas mostrar una relación que cruza niveles, hazlo en el diagrama del nivel más alto de los dos, representando el otro extremo como una caja de ese nivel; no bajes clases al diagrama de containers. Un diagrama, un nivel.

Poner los diagramas en una wiki aparte (de comodidad). Qué pasa: los diagramas y ADRs viven en Confluence, Notion o una carpeta de Drive, separados del código. Al principio es cómodo (herramientas bonitas de dibujo); a los seis meses, todo está desactualizado y miente. Por qué pasa: las herramientas de wiki son más agradables para dibujar que un archivo de texto en el repo, y la comodidad de hoy gana sobre el mantenimiento de mañana. Cómo detectarlo: si tu diagrama vive en un sistema donde el código no puede "verlo" y no cambia en el mismo commit que el código, se va a pudrir. Cómo corregirlo: docs-as-code —diagramas como texto (mermaid, diagram-as-code) y ADRs en Markdown, en el mismo repositorio, revisados en el mismo pull request que el código que describen—.

Ejercicios

Ejercicio 1 — Diagnostica el diagrama. Un diagrama de Mercado contiene: 3 personas, la caja del sistema Mercado, 5 containers, 6 componentes de la API, 4 clases del checkout, 2 sistemas externos, y unas 40 flechas. Pásalo por las dos reglas de la lección: ¿mezcla niveles? ¿es espagueti? ¿cuál es el veredicto y cómo lo arreglas?

Ver solución

¿Mezcla niveles? Sí. Tiene elementos internos de tres rangos distintos: containers (rango 2), componentes (rango 3) y clases (rango 4). Las personas y los sistemas externos no cuentan como mezcla (son contexto/decorado), pero containers + componentes + clases en una sola lámina son tres niveles de zoom encimados. Es el mapa con calles, metro y tuberías juntos.

¿Es espagueti? Sí. Cuenta los elementos: 3 personas + 1 sistema + 5 containers + 6 componentes + 4 clases + 2 externos = 21 elementos, más 40 flechas. Pasa el límite legible de 20, y 40 flechas son imposibles de seguir con el ojo.

Veredicto: RECHAZADO por las dos reglas a la vez (el patrón típico: los dos fracasos van juntos).

Cómo lo arreglas: partiéndolo en el conjunto de diagramas del C4, uno por nivel. (1) Un Context: las 3 personas, Mercado como una caja, los 2 externos —5-6 elementos, legible—. (2) Un Container: las 5 piezas desplegables con personas y externos como decorado —9 elementos, legible—. (3) Un Component solo del container que lo amerite (la API/checkout): sus 6 componentes —legible—. Las 4 clases del checkout no van en ningún diagrama dibujado a mano: se leen del código o se generan (nivel Code). Resultado: 2-3 diagramas limpios que juntos contienen toda la información del monstruo original, pero cada uno comunica. La completitud vive en el conjunto, no en la lámina.

Ejercicio 2 — El documento que nadie lee. El arquitecto de Mercado escribió un documento de arquitectura de 180 páginas: incluye la historia de cada decisión, diagramas de los cuatro niveles de cada container, listados de endpoints, esquemas de tablas, y un glosario. Seis meses después, el onboarding de los devs nuevos sigue tardando dos semanas y nadie cita el documento. ¿Qué salió mal y qué debió producir en su lugar?

Ver solución

Salió mal la confusión de completitud con comunicación: el arquitecto produjo un artefacto exhaustivo pensando que "más completo = mejor documentado", pero 180 páginas son inservibles para el uso real —cuando el dev nuevo necesita orientarse, no va a leer 180 páginas; se rinde y pregunta a la gente, y por eso el onboarding sigue en dos semanas—. El documento es un archivo, no una comunicación: existe, da la sensación de estar documentado, y no lo usa nadie. Además, un documento así de grande se pudre: mantener 180 páginas al día es imposible, así que a los seis meses buena parte ya miente.

Qué debió producir: poco y vivo, dirigido al uso. Para el onboarding —el problema concreto que no se resolvió— un README corto en el repo con el Context y el Container (los dos diagramas que orientan) y tres párrafos de "cómo corres el sistema local y por dónde empezar". Para el porqué de las decisiones importantes, un puñado de ADRs cortos en el repo, no la "historia de cada decisión" en prosa. Para el detalle (endpoints, esquemas), enlazar a lo que se genera del código y siempre está al día, no copiarlo a mano al documento. El resultado: en vez de 180 páginas muertas, un README + Context + Container + unos ADRs, todo en el repo, versionado con el código, que un dev nuevo de verdad lee y usa para arrancar en dos días. Menos, vivo, usado —vence a más, muerto, ignorado—.

Ejercicio 3 — ¿Por qué se pudrió? Dos equipos documentan igual de bien (buenos diagramas C4, buenos ADRs), pero al año el equipo A tiene documentación al día y el equipo B tiene documentación que miente. La única diferencia: A guarda sus diagramas como archivos mermaid y sus ADRs como Markdown en el repositorio del código; B los guarda en una wiki corporativa aparte, muy bonita. Explica por qué esa sola diferencia produjo resultados opuestos, y qué principio lo captura.

Ver solución

La diferencia decisiva es si la documentación comparte el flujo de trabajo del código. En el equipo A, un diagrama es un archivo de texto en el mismo repo: cuando alguien cambia el código en un pull request, el diagrama afectado está ahí mismo, el autor lo actualiza en el mismo cambio, y el revisor lo ve y lo exige. Actualizar la doc no es un paso aparte que se olvida; es parte del mismo commit. La doc se mantiene viva porque no puede desincronizarse sin que alguien lo note en la revisión.

En el equipo B, el diagrama vive en una wiki, en otro sistema, en otro flujo. Cuando alguien cambia el código, nada en su flujo de trabajo le recuerda que existe un diagrama en la wiki; actualizarlo es un acto voluntario, separado, que compite con las prisas del día. La mayoría de las veces no ocurre. La doc se pudre porque está estructuralmente desconectada del código que describe —no por descuido de las personas, sino por dónde vive—.

El principio que lo captura es docs-as-code: la documentación se versiona con el código, en el mismo repositorio, y cambia en la misma revisión. No es que las herramientas de wiki sean malas —es que separar la doc del código garantiza que se desincronicen—. Por eso todo este módulo empujó hacia artefactos chicos y textuales (mermaid, ADRs en Markdown, generar el Code): no por gusto minimalista, sino porque son los que pueden vivir en el repo y compartir el destino del código. La documentación que sobrevive es la que viaja con lo que describe.

Resumen y siguiente paso

En esta lección aprendiste a reconocer y evitar los tres modos en que la comunicación de arquitectura sale mal, casi siempre por exceso mal dirigido. El documento de 500 páginas (documentar de más, comunicar de menos) y el diagrama-espagueti (mostrar todo, comunicar nada) comparten la raíz de confundir completitud con comunicación —y viste, con el mapa que dibuja todas las capas, que comunicar exige omitir—. Volviste medibles las dos reglas: un diagrama no debe mezclar niveles de abstracción (containers con componentes con clases) ni exceder el límite legible —el validador rechazó el "muestra todo" con 24 elementos y tres niveles, y aprobó el Container limpio con 9 y uno—. Y viste el tercer fracaso, el diagrama que se pudre por vivir aparte del código, y su cura: docs-as-code, la documentación versionada con el código para que comparta su destino.

Antes de avanzar deberías poder: diagnosticar un diagrama con las dos reglas (mezcla de niveles, conteo de elementos) y partirlo en el conjunto limpio del C4; explicar por qué un documento gigante o un diagrama total comunican menos, no más; y justificar docs-as-code como la defensa contra el diagrama que miente.

Lo que sigue es juntar todo. En la lección 8, el proyecto, vas a actuar como el arquitecto de Mercado y producir su paquete de comunicación para dos audiencias: el Context para el VP, el Container para el dev nuevo, un ADR que comunique el porqué de una decisión, y la validación ejecutada de que cada mapa apunta al nivel correcto para su audiencia y pasa las reglas de higiene que acabas de aprender. Es el paso de "sé cada herramienta por separado" a "sé ensamblar el paquete completo que comunica una arquitectura a quienes la necesitan".

Recursos

← Anterior6. El ADR como comunicación: el porqué que viaja en el tiempoSiguiente →8. Proyecto: comunica la arquitectura de Mercado para dos audiencias