Módulo 3: Comunicar la arquitectura

5. El diagrama correcto para la audiencia

Siguiente →

Descripción

Al terminar esta lección vas a dominar la habilidad que gobierna a todas las demás de este módulo: elegir el diagrama correcto para la audiencia que tienes enfrente. Ya sabes dibujar los cuatro niveles del C4; ahora aprendes lo más difícil, que es decidir cuál de los cuatro le das a cada persona. La tesis es directa y tiene consecuencias: el mapa para el VP no es el mismo que para el dev. No es que uno sea "mejor" y otro "peor" —los dos son correctos—; es que cada audiencia trae una pregunta distinta y necesita un zoom distinto para responderla. Darle a alguien el nivel equivocado no es un detalle estético: es la diferencia entre comunicar y no comunicar. Y el error va en las dos direcciones —dar un nivel de más ahoga a la persona en detalle, dar un nivel de menos la deja sin poder trabajar—, así que no basta con "simplificar siempre" ni con "detallar siempre": hay que apuntar al nivel que la audiencia necesita.

Esto importa porque es el error de comunicación más común y más caro, y casi nadie lo diagnostica como lo que es. Cuando una reunión de negocio no avanza, o un dev nuevo tarda semanas en arrancar, rara vez alguien dice "le dimos el zoom equivocado" —se culpa a que "el sistema es muy complejo", a que "el dev es lento", a que "el VP no es técnico"—. Pero muchísimas veces la causa real es que la comunicación apuntó al nivel equivocado: al VP le mostraron el mapa de la calle, al dev le mostraron el mapa del mundo. El arquitecto que aprende a emparejar audiencia con nivel arregla, de un solo golpe, una cantidad enorme de fricción que los demás atribuyen a causas difusas. Es una de las palancas más baratas y más ignoradas del oficio.

Conexión con el módulo: en las lecciones 2, 3 y 4 construiste y dibujaste las cuatro herramientas —los cuatro niveles del C4—. Esta lección es donde aprendes a usarlas con criterio: no cómo dibujar cada nivel, sino cuál elegir para quién. Es el corazón del módulo, la razón de que todo lo anterior exista. En la lección 6 añadirás la pieza que los diagramas no cubren —el porqué, con el ADR—, y en la 7 te protegerás de los fracasos (el doc gigante, el espagueti). Y en el proyecto (lección 8) vas a ejercer exactamente esta habilidad: producir el paquete de Mercado eligiendo el nivel correcto para el VP y para el dev.

El médico que ajusta la explicación al paciente

Piensa en un buen médico que acaba de leer tus estudios y tiene que explicarte un diagnóstico. Si le hablara a un colega médico, usaría los términos técnicos precisos: los valores exactos de laboratorio, el nombre latino de la condición, el mecanismo fisiopatológico. A ti, que no eres médico, te dice lo mismo pero a otro nivel: "tienes el azúcar un poco alto; si cambiamos la dieta y caminas media hora al día, lo controlamos". No te está mintiendo ni ocultando información: te está dando el zoom que tú puedes usar para actuar. Contarte el mecanismo fisiopatológico completo no te haría más sano; te abrumaría y saldrías del consultorio sin saber qué hacer.

Ahora invierte la situación. Si ese mismo médico le dijera a su colega especialista "el azúcar está un poco alto, hay que cuidar la dieta", el colega se quedaría corto —necesita los valores exactos, la evolución, los diferenciales para decidir un tratamiento—. El nivel que era perfecto para ti sería insuficiente para el especialista. Y aquí está la clave: el error va en las dos direcciones. Darle al paciente la explicación del especialista lo ahoga; darle al especialista la explicación del paciente lo deja sin poder trabajar. Un buen médico no "simplifica siempre" ni "detalla siempre": lee a quién tiene enfrente y apunta al nivel que esa persona puede usar.

Comunicar arquitectura es exactamente eso. El VP es el paciente: necesita el Context ("Mercado conecta compradores y vendedores, cobra y envía") para poder decidir, y el detalle técnico lo abruma. El dev es el especialista: necesita el Container o el Component para poder trabajar, y el Context le queda corto. No hay un diagrama "correcto" en abstracto —hay un diagrama correcto para cada quien—. El arquitecto, como el médico, lee a su audiencia y ajusta el zoom.

Los dos guiones de Mercado

Aterricémoslo en las dos conversaciones concretas que el arquitecto de Mercado tiene esta semana.

Guion 1: la reunión con el VP de producto. El VP quiere lanzar la venta a vendedores externos por API y necesita entender dónde encaja eso. El arquitecto pone en la pantalla el Context (nivel 1): Mercado como una caja, rodeada de clientes, vendedores, el gateway de pagos y el carrier de envíos. Señala la relación con "vendedores" y dice: "hoy los vendedores publican por la web; lo que propones es que puedan hacerlo también por una API, aquí". El VP lo entiende en un minuto, ve la implicación (más vendedores, más carga en pagos y envíos), y la conversación avanza a lo que importa: presupuesto, prioridades, riesgos de negocio. Cinco cajas hicieron el trabajo. Si el arquitecto hubiera proyectado el Container con sus nueve piezas técnicas, el VP habría preguntado "¿qué es Elasticsearch?" y la reunión se habría perdido en un tutorial.

Guion 2: el onboarding del dev nuevo. La dev nueva llegó el lunes y en dos semanas tiene que arreglar un bug en el flujo de pedidos. El arquitecto le muestra el Container (nivel 2): las cinco piezas de Mercado, sus tecnologías, cómo una petición fluye del navegador a la API a la base de datos. La dev ve dónde vive el flujo de pedidos (la API), qué lo rodea, y arranca a leer código con un mapa en la cabeza. Si el bug estuviera en el checkout —enredado—, el arquitecto bajaría un peldaño más y le mostraría el Component del checkout, para que ubique el Tax Calculator sin perderse. Si en cambio le hubiera mostrado solo el Context —"Mercado vende cosas"—, la dev habría pasado su primera semana preguntándole a todos dónde está cada cosa, porque el mapa del mundo no dice dónde tocar el código.

Mismo sistema, dos guiones, dos niveles. La habilidad no es dibujar —eso ya lo sabes— es elegir. Vamos a convertir esa elección en algo medible.

Ejemplo trabajado: el recomendador y el detector de desajuste

La elección de nivel se puede sistematizar: para cada audiencia hay un nivel recomendado, y dado un nivel que alguien recibió de verdad, se puede detectar el desajuste y su dirección —de más (se ahoga) o de menos (no puede trabajar)—. El siguiente código hace las dos cosas: primero imprime la tabla audiencia→nivel recomendado, y luego audita qué mapa recibió cada quien esta semana en Mercado, marcando cada desajuste con su dirección y su costo.

# El mapa correcto para la audiencia.
# Recomendador: para cada audiencia, el nivel C4 que necesita.
# Detector: dada (audiencia, nivel mostrado), marca el desajuste y su direccion.

level_rank = {"Context": 1, "Container": 2, "Component": 3, "Code": 4}

recommended = {
    "VP de producto":             "Context",
    "cliente o inversionista":    "Context",
    "arquitecto de otro equipo":  "Container",
    "dev nuevo en el equipo":     "Container",
    "dev trabajando en checkout": "Component",
    "dev editando ese archivo":   "Code",
}

print("Audiencia -> nivel C4 recomendado")
print("-" * 52)
for audience, level in recommended.items():
    print(f"  {audience:<28} {level}")
print()

# Auditoria: que mapa recibio cada quien esta semana en Mercado.
shown = [
    ("VP de producto",             "Component"),
    ("dev nuevo en el equipo",     "Context"),
    ("dev trabajando en checkout", "Component"),  # correcto
    ("cliente o inversionista",    "Container"),
]

print("Auditoria de la semana (que mapa recibio cada quien):")
print("-" * 52)
for audience, level in shown:
    want = recommended[audience]
    if level == want:
        print(f"  OK   {audience:<28} {level:<10} correcto")
    else:
        gap = level_rank[level] - level_rank[want]
        if gap > 0:
            print(f"  MAL  {audience:<28} {level:<10} +{gap} de mas (se ahoga en detalle; queria {want})")
        else:
            print(f"  MAL  {audience:<28} {level:<10} {gap} de menos (no puede trabajar; queria {want})")

Qué esperar. Al correrlo:

Audiencia -> nivel C4 recomendado
----------------------------------------------------
  VP de producto               Context
  cliente o inversionista      Context
  arquitecto de otro equipo    Container
  dev nuevo en el equipo       Container
  dev trabajando en checkout   Component
  dev editando ese archivo     Code

Auditoria de la semana (que mapa recibio cada quien):
----------------------------------------------------
  MAL  VP de producto               Component  +2 de mas (se ahoga en detalle; queria Context)
  MAL  dev nuevo en el equipo       Context    -1 de menos (no puede trabajar; queria Container)
  OK   dev trabajando en checkout   Component  correcto
  MAL  cliente o inversionista      Container  +1 de mas (se ahoga en detalle; queria Context)

Lee la auditoría con cuidado, porque cuenta toda la historia. Tres de cuatro comunicaciones fallaron esta semana, y fallaron en las dos direcciones. El VP recibió Component: dos niveles de más, se ahoga —el caso del paciente al que le dieron la explicación del especialista—. El dev nuevo recibió Context: un nivel de menos, no puede trabajar —el especialista al que le dieron la explicación del paciente—. El cliente recibió Container: un nivel de más, otra vez detalle que no puede usar. Solo el dev del checkout, que recibió Component, dio en el blanco.

Fíjate en lo que la columna de "dirección" revela: el desajuste no es siempre "dieron demasiado". Dos veces fue de más (VP, cliente) y una de menos (dev nuevo). Por eso la regla no puede ser "siempre simplifica" —eso arreglaría al VP y al cliente pero empeoraría al dev nuevo, que ya recibió muy poco—. La regla correcta es apuntar: leer la pregunta de la audiencia y darle el nivel que la responde, ni uno más ni uno menos. El recomendador de arriba no es un oráculo mágico; es el hábito de preguntarte, antes de mostrar cualquier diagrama, "¿quién mira esto y qué pregunta trae?" —y esa pregunta, hecha a tiempo, evita las tres fallas de la semana—.

El costo de cada dirección del desajuste

Vale la pena entender por qué cada dirección del desajuste hace daño, porque son daños distintos.

Nivel de más: el ahogo en detalle. Cuando le das a alguien un zoom más fino del que necesita, no le das "información extra que quizás use" —le das ruido que le tapa la señal—. El VP que ve el Component del checkout no piensa "qué bien, ahora sé más"; piensa "no entiendo nada de esto, mejor confío en el equipo". El exceso de detalle no suma comprensión: la resta, porque la idea principal (qué hace el sistema, dónde encaja lo nuevo) queda enterrada bajo piezas que la audiencia no puede procesar. El costo es una decisión tomada a ciegas o una aprobación por fe, no por entendimiento —y eso se cobra después, cuando esa persona no tiene el modelo mental para la siguiente conversación—.

Nivel de menos: la parálisis. Cuando le das a alguien un zoom más grueso del que necesita, lo dejas sin la información para actuar. El dev nuevo que solo ve el Context sabe "Mercado vende cosas" pero no sabe dónde tocar el código, así que no puede empezar: tiene que ir persona por persona preguntando "¿dónde está el flujo de pedidos?", reconstruyendo a mano el mapa que debió recibir. El costo es tiempo perdido y dependencia de otros —el onboarding de dos semanas que debió ser de dos días—. La parálisis es más visible que el ahogo (el dev sabe que está atascado), pero igual de cara.

La lección de tener las dos direcciones a la vista: no hay un default seguro. "Siempre detalla" ahoga a los de arriba; "siempre simplifica" paraliza a los de abajo. La única regla que funciona es leer a la audiencia y apuntar. Por eso esta habilidad es criterio, no receta.

Cuando no conoces a la audiencia: pregunta por la pregunta

El recomendador supone que ya sabes quién mira —"VP de producto", "dev nuevo"—. Pero en la vida real muchas veces te piden "un diagrama del sistema" sin decirte para quién ni para qué, y elegir el nivel a ciegas es adivinar. El arreglo no es memorizar más categorías de audiencia: es aprender a preguntar por la pregunta antes de dibujar nada.

La técnica es una sola pregunta, hecha a tiempo: "¿qué vas a hacer con este diagrama?" —o su variante, "¿qué decisión o tarea te tiene aquí?"—. La respuesta te da el nivel directo, porque el nivel del C4 no lo determina el cargo de la persona sino la tarea que trae:

  • Si te contestan "quiero entender qué hace el sistema para decidir si invertimos / aprobamos / integramos a alto nivel" → es una tarea del mundo → Context.
  • Si te contestan "voy a trabajar en el sistema y necesito ubicarme" → es una tarea de la ciudad → Container.
  • Si te contestan "voy a modificar esta pieza concreta por dentro" → es una tarea del barrio → Component.

Fíjate en que la misma persona puede necesitar niveles distintos según la tarea: el mismo VP que hoy quiere el Context para aprobar un proyecto, mañana —si se mete a revisar por qué un módulo es lento— podría necesitar que le expliques algo del Container. No etiquetes a la persona de una vez y para siempre; lee la pregunta de hoy. Por eso el recomendador es un punto de partida, no una ley: mapea audiencias típicas a niveles típicos, pero la señal más confiable es siempre la tarea concreta que la persona viene a resolver.

Hay un beneficio secundario de preguntar por la pregunta: te protege del error de vanidad técnica. Cuando arrancas por "¿qué vas a hacer con esto?", tu cerebro se orienta hacia lo que la persona necesita hacer en vez de hacia lo que tú quieres mostrar. La conversación deja de ser "déjame enseñarte lo que sé del sistema" y se vuelve "déjame darte lo que necesitas para tu tarea" —que es, exactamente, la diferencia entre comunicar y lucirte—. Una pregunta de diez segundos antes de abrir el diagrama evita la mayoría de los desajustes que midió el ejemplo trabajado.

Y un truco que cierra el círculo: escribe la audiencia en el título del propio diagrama. En vez de titular una lámina "Arquitectura de Mercado" —que no dice para quién es—, titúlala "Mercado — System Context (para negocio)" o "Mercado — Containers (para desarrollo)". Esto tiene dos efectos. Para ti, el que dibuja: poner la audiencia en el título te obliga a decidirla antes de dibujar, así que ya no puedes caer en el diagrama-para-nadie. Para quien lo recibe después —quizás meses más tarde, sin ti en la sala—: el título le dice de un vistazo si este es su mapa o si debería buscar otro nivel. Un diagrama sin audiencia declarada es un diagrama que invita al desajuste, porque cualquiera lo abre sin saber si le corresponde. Los títulos de los diagramas C4 de este módulo llevan esa marca a propósito ("el mapa del VP", "el mapa del dev"): no es decoración, es parte de comunicar el nivel.

Errores comunes

Reciclar el diagrama más detallado para todos (de reúso perezoso). Qué pasa: el arquitecto hizo un Container muy completo (le costó trabajo) y lo usa igual con el VP, con el dev nuevo y con el cliente, porque "ya está hecho". Uno se ahoga, otro va bien por casualidad, otro no encuentra lo que busca. Por qué pasa: hacer un diagrama cuesta, y reusar el que ya existe se siente eficiente. Cómo detectarlo: si el mismo archivo de diagrama aparece en una junta de negocio y en un onboarding técnico, estás reciclando el zoom equivocado para al menos una audiencia. Cómo corregirlo: ten los dos o tres diagramas del sistema listos (Context, Container, y el Component crítico) y elige cuál mostrar según quién entra a la sala; el costo de tener varios se paga solo con no perder ninguna conversación.

Creer que "más detalle" siempre es "más profesional" (de vanidad técnica). Qué pasa: el arquitecto muestra el diagrama más denso que tiene porque exhibir dominio técnico se siente como hacer bien el trabajo —"mira todo lo que sé del sistema"—. La audiencia de negocio queda impresionada y perdida. Por qué pasa: se confunde impresionar con comunicar; el detalle da estatus. Cómo detectarlo: si eliges qué mostrar por lo que te hace ver competente en vez de por lo que la audiencia puede usar, es vanidad, no comunicación. Cómo corregirlo: mide el éxito por lo que la audiencia entendió y pudo hacer, no por lo impresionado que se vio; para el VP, cinco cajas que lo dejan decidir valen más que treinta que lo dejan mudo.

Simplificar de más "para no abrumar" al técnico (de sobrecorrección). Qué pasa: alguien aprendió que "hay que simplificar" y ahora le da a todos el Context, incluido el dev nuevo que necesita el Container. El dev se queda sin poder trabajar. Por qué pasa: se toma "simplifica para el negocio" como regla universal en vez de como una de las dos direcciones. Cómo detectarlo: si un técnico te pide "¿y por dentro cómo es?" y tú insistes en la vista de alto nivel, simplificaste de más. Cómo corregirlo: recuerda que el error va en las dos direcciones —al de negocio le das el zoom grueso, al técnico el fino—; la regla no es simplificar, es apuntar al nivel que responde la pregunta de quien tienes enfrente.

Ejercicios

Ejercicio 1 — Empareja y detecta. Cuatro personas recibieron un diagrama de Mercado esta semana. Di si el nivel fue correcto y, si no, en qué dirección falló (de más / de menos) y qué debieron recibir: (a) un inversionista recibió el Container; (b) una dev que va a refactorizar el Tax Calculator recibió el Component del checkout; (c) el VP de operaciones recibió el diagrama de clases del módulo de envíos; (d) un ingeniero de un equipo socio que va a integrarse por API recibió el Context.

Ver solución
  • (a) Inversionista con Container → de más (+1). El inversionista quiere el Context (qué es, con quién habla). El Container le mete piezas técnicas que no evalúa; se ahoga un poco. Debió recibir Context.
  • (b) Dev refactorizando Tax Calculator con Component del checkout → correcto. Va a trabajar dentro de esa pieza; el Component le muestra dónde vive el Tax Calculator y qué lo rodea. Nivel exacto. (Para el detalle último de clases, abriría el código, no un diagrama de Code.)
  • (c) VP de operaciones con diagrama de clases → de más (+3, el peor desajuste). Un VP con un diagrama de nivel Code está tres niveles por encima de lo que puede usar; ahogo total. Debió recibir Context (o a lo sumo un Container acotado si su pregunta era muy operativa).
  • (d) Ingeniero que integra por API con Context → de menos (-1). Necesita saber con qué pieza habla y cómo —eso es Container—. El Context no le muestra la API. No puede integrar con lo que recibió. Debió recibir Container.

Dos de más, uno de menos, uno correcto: el patrón real: el desajuste va en las dos direcciones y hay que leer cada caso, no aplicar una regla única.

Ejercicio 2 — La regla que no funciona. Un equipo, harto de perder reuniones con negocio, adopta la regla: "de ahora en adelante, a todo el mundo le mostramos solo el Context; así nadie se abruma". ¿Qué problema nuevo crea esta regla, y por qué "simplificar siempre" no es la solución? Propón la regla correcta.

Ver solución

La regla crea el problema opuesto: paraliza a las audiencias técnicas. El dev nuevo, el ingeniero que integra, el equipo de ops —todos los que necesitan el Container o el Component para trabajar— ahora reciben solo el Context, que les queda corto. Arreglaron el ahogo de negocio a costa de la parálisis técnica: los devs vuelven a perder días reconstruyendo a mano el mapa de la ciudad que la regla les niega. Cambiar "siempre detalla" por "siempre simplifica" no elimina el desajuste; solo lo mueve de una audiencia a otra.

"Simplificar siempre" no funciona porque el error de comunicación va en las dos direcciones: hay quien recibe de más (y se ahoga) y quien recibe de menos (y se paraliza). Ninguna regla de dirección única —ni "detalla" ni "simplifica"— acierta con las dos audiencias, porque tienen necesidades opuestas. La regla correcta es apuntar: para cada persona, dar el nivel que responde su pregunta —Context al negocio, Container al dev que se orienta, Component al que trabaja dentro de una pieza—. Cuesta más (hay que leer a cada audiencia y tener varios diagramas listos) pero es la única que comunica a todos. La comodidad de una regla única siempre se paga con una audiencia mal servida.

Ejercicio 3 — La misma reunión, dos audiencias. El arquitecto de Mercado presenta el plan de abrir la API a vendedores externos ante una sala mixta: están el VP de producto y dos desarrolladores que van a construirlo. No puede darle a la sala un solo nivel sin fallarle a alguien. ¿Cómo estructuras la comunicación para servir a las dos audiencias en la misma reunión?

Ver solución

La clave es no buscar "el diagrama que sirva a los dos" —no existe, porque tienen preguntas distintas— sino secuenciar los niveles y ser explícito sobre para quién es cada uno. Una estructura que funciona:

  1. Empieza con el Context, para todos. "Aquí está Mercado y su mundo; lo que proponemos es esta nueva relación —vendedores externos por API—, aquí." Con esto el VP tiene todo lo que necesita para su decisión (encaje, implicaciones de negocio, riesgo) y los devs tienen el marco. Nadie se ahoga, nadie se pierde: el Context es el terreno común.
  2. Anuncia el cambio de zoom. "Con eso, VP, tienes la foto para decidir. Ahora bajo un nivel para el equipo técnico; si quieres seguirlo, bienvenido, pero la decisión de negocio ya está sobre la mesa." Esto le da permiso al VP de desconectar sin sentirse excluido, y a los devs de recibir lo suyo.
  3. Baja al Container (y al Component del checkout si aplica), para los devs. Ahora sí muestras dónde vive la nueva API, qué piezas toca, cómo fluye. Los devs obtienen su mapa de trabajo.

La técnica general: el Context es el idioma común donde arranca toda reunión mixta, y de ahí bajas por niveles anunciando el cambio de audiencia. Así cada quien recibe su zoom sin que el otro se ahogue ni se pierda, y —bonus— el acto de anunciar "ahora bajo un nivel" le enseña a la sala el modelo mental de que hay niveles. Es exactamente subir y bajar por el elevador del arquitecto, en vivo.

Resumen y siguiente paso

En esta lección aprendiste la habilidad que gobierna al módulo entero: elegir el diagrama correcto para la audiencia. Con el médico que ajusta la explicación al paciente viste que no hay un diagrama "correcto" en abstracto —hay uno correcto para cada quien—, y que el error va en las dos direcciones: un nivel de más ahoga en detalle, un nivel de menos deja sin poder trabajar. Lo mediste: en una semana de Mercado, tres de cuatro comunicaciones fallaron —dos por exceso (VP, cliente), una por defecto (dev nuevo)—, lo que prueba que "siempre simplifica" no es la solución. La regla que funciona es apuntar: leer la pregunta de la audiencia y dar el nivel que la responde, ni uno más ni uno menos.

Antes de avanzar deberías poder: emparejar una audiencia con su nivel de C4 y justificar por qué; diagnosticar un desajuste y nombrar su dirección (de más / de menos) y su costo (ahogo / parálisis); y estructurar una reunión mixta secuenciando niveles desde el Context común.

Lo que sigue añade la pieza que los diagramas, por sí solos, no cubren. Un diagrama comunica muy bien el qué —qué piezas hay, cómo se conectan, cómo se ve el sistema hoy— pero es mudo sobre el por qué el sistema es así. En la lección 6 vas a usar el ADR como herramienta de comunicación: el porqué de una decisión, empaquetado para viajar en el tiempo hasta el dev que llegue en dos años y necesite entender por qué Mercado es como es, sin poder preguntarle a nadie. Es el paso de "sé mostrar la foto del sistema al nivel correcto" a "sé dejar registrada la historia de por qué la foto se ve así".

Recursos

← Anterior4. Component y Code: cuándo bajar y cuándo pararSiguiente →6. El ADR como comunicación: el porqué que viaja en el tiempo