Módulo 7: Documentación que sobrevive
El sistema C4 + ADR + arc42
Descripción
Las dos lecciones anteriores resolvieron dónde poner la doc (en el repo, cerca del código) y cómo mantenerla sincronizada (docs-as-code, validada en CI). Esta lección resuelve qué documentar y cómo esas piezas se ensamblan en un sistema. Porque hay un error silencioso en cómo mucha gente piensa la documentación de arquitectura: la imagina como un artefacto —"el diagrama" o "el documento"— cuando en realidad es un sistema de piezas complementarias, cada una diseñada para responder un tipo distinto de pregunta. El combo que esta lección arma es el que ha demostrado sobrevivir: el C4 (los diagramas por nivel que muestran la estructura), el ADR (el registro de decisiones que guarda el porqué), y arc42 (la plantilla que organiza todo eso y cubre lo que ni el C4 ni el ADR alcanzan).
La idea central es que ninguna de las tres piezas alcanza sola, y esta lección lo mide. Un diagrama C4 impecable te muestra qué piezas hay y cómo se conectan, pero no te dice por qué se decidieron así —para eso está el ADR—. Una colección de ADRs perfecta te explica el porqué de cada decisión, pero no te da el mapa de la estructura ni la lista de atributos de calidad —para eso están el C4 y arc42—. Y arc42, que es la plantilla, te da el esqueleto —los lugares donde va cada cosa, incluidos los que el C4 y el ADR no cubren: los atributos de calidad, las restricciones, los riesgos— pero se llena con C4 y ADRs, no los reemplaza. Las tres juntas responden lo que una persona nueva o un auditor necesitan saber; cada una sola deja huecos. Esta lección ejecuta la cobertura de cada una y demuestra por qué el sistema completo es más que la suma —y qué añade específicamente arc42 como el esqueleto que las sostiene—.
Conexión con el módulo. Es la lección que ensambla el sistema. Las lecciones 2 y 3 dijeron dónde y cómo vive la doc; esta dice de qué está hecha. Con la analogía del módulo: si la doc que sobrevive es la carpeta que el dueño anterior te dejó, esta lección es sobre las pestañas de esa carpeta —una para el mapa (C4), una para las decisiones (ADR), y la estructura de la carpeta misma con sus secciones (arc42)—. Frontera, y es la más importante de esta lección: aquí no se re-enseña a dibujar el C4 (eso fue el módulo 3 de esta guía) ni la mecánica de escribir un ADR (eso es la guía hermana architecture-decisions). Se asume que ya sabes producir esas piezas; esta lección enseña a ensamblarlas en un sistema que dura y a ver qué hueco llena cada una —el criterio de la documentación completa, no el manual de cada herramienta—.
Una analogía: el archivador con pestañas contra la pila de papeles
Piensa en cómo un dueño de casa organiza —o no— todos los papeles importantes de su casa, y en dos maneras de hacerlo.
La pila de papeles. El dueño tiene todos los documentos de la casa, pero en una sola pila sobre el escritorio: el plano, las escrituras, las garantías de los electrodomésticos, las notas de por qué la cisterna se cambió de lugar, los recibos, los manuales. Toda la información existe —nada se perdió— pero encontrar algo es una pesadilla: para saber por qué la cisterna está donde está, hay que escarbar toda la pila esperando dar con la nota correcta. Y peor: como no hay estructura, es imposible saber qué falta. ¿Está documentada la capacidad eléctrica de la casa? ¿Los riesgos conocidos, como que el techo gotea en tormentas fuertes? Nadie sabe, porque no hay un lugar designado para esas cosas donde su ausencia se notaría. La pila tiene mucha información y ninguna forma de usarla ni de auditar qué le falta.
El archivador con pestañas. Otro dueño usa un archivador con pestañas etiquetadas, cada una para un tipo de información: pestaña "planos" (cómo está construida la casa), pestaña "decisiones" (por qué la cisterna se movió, por qué los muros de carga están donde están), pestaña "atributos" (capacidad eléctrica, aislamiento térmico, cuánta agua aguanta), pestaña "riesgos" (el techo gotea en tormentas, la instalación es vieja en el ala este). Ahora, encontrar algo es directo: cada pregunta tiene su pestaña. Y —esto es lo poderoso— la estructura misma revela lo que falta: si la pestaña "riesgos" está vacía, saltará a la vista que nadie documentó los riesgos, porque hay un lugar designado esperándolos. El archivador no solo guarda la información; la organiza de modo que sea encontrable y su ausencia sea visible.
Aquí está el sistema de esta lección: arc42 es el archivador con pestañas; el C4 y el ADR son contenido que va en pestañas específicas. La pestaña "planos" del archivador es donde vive el C4 (la estructura); la pestaña "decisiones" es donde viven los ADRs (el porqué); y arc42 añade pestañas que ni el C4 ni el ADR traen —"atributos de calidad", "restricciones", "riesgos"— que sin un lugar designado quedarían como la pila: información que falta y que nadie nota que falta. La pila de papeles es tener C4 y ADRs sueltos sin un esqueleto que los organice y muestre los huecos. El archivador con pestañas es el sistema completo: cada tipo de conocimiento en su lugar, encontrable, y con las ausencias visibles. Esta lección mide por qué necesitas el archivador entero y no solo algunas pestañas.
Ejemplo trabajado: la cobertura de cada pieza y del combo
Vamos a medir la afirmación central: ninguna pieza sola alcanza. Tomamos las preguntas que una persona nueva o un auditor le hacen a la documentación de un sistema —ocho preguntas concretas sobre Mercado— y vemos qué artefacto responde cada una. Luego medimos qué fracción de esas preguntas cubre cada "kit" de documentación usado solo, y qué cubre el combo.
Las ocho preguntas se reparten en tres familias: las de estructura (qué hay, cómo se conecta) las responde el C4; las de porqué (por qué se decidió así) las responde el ADR; y las de calidad, restricciones y riesgos las responde arc42 en sus secciones dedicadas. Veamos la cobertura:
# El sistema de documentacion: C4 + ADR + arc42 no son tres cosas sueltas, son un
# SISTEMA. Cada artefacto responde un tipo de pregunta; juntos cubren lo que una
# persona nueva o un auditor necesita saber. arc42 es el ESQUELETO que los organiza.
# Mapeamos preguntas reales al artefacto que las responde y medimos la cobertura.
QUESTIONS = [
# (pregunta, artefacto que la responde)
("Que hace el sistema y quien lo usa?", "C4-Context"),
("De que piezas desplegables se compone?", "C4-Container"),
("Como se estructura una pieza por dentro?", "C4-Component"),
("Por que se eligio la cola en vez de escritura directa?", "ADR"),
("Por que payments es un servicio aparte?", "ADR"),
("Cuales son los atributos de calidad y sus metas?", "arc42-quality"),
("Cuales son las restricciones tecnicas del sistema?", "arc42-constraints"),
("Que riesgos y deuda tecnica conocemos?", "arc42-risks"),
]
# Que cubre cada "kit" de documentacion si se usa SOLO:
KITS = {
"solo C4": {"C4-Context", "C4-Container", "C4-Component"},
"solo ADR": {"ADR"},
"solo arc42": {"arc42-quality", "arc42-constraints", "arc42-risks"},
"C4+ADR+arc42": {"C4-Context", "C4-Container", "C4-Component", "ADR",
"arc42-quality", "arc42-constraints", "arc42-risks"},
}
total = len(QUESTIONS)
print(f"{'kit':<16}{'responde':>12}{'cobertura':>12}")
print("-" * 40)
for kit, artifacts in KITS.items():
answered = sum(1 for _, art in QUESTIONS if art in artifacts)
print(f"{kit:<16}{answered:>9}/{total}{answered / total * 100:>10.0f}%")
print("-" * 40)
for kit in ("solo C4", "solo ADR", "solo arc42"):
gaps = [q for q, art in QUESTIONS if art not in KITS[kit]]
print(f"\n{kit} deja SIN responder ({len(gaps)}):")
for q in gaps:
print(f" - {q}")Qué esperar. Al correr el archivo, la salida es exactamente esta:
kit responde cobertura
----------------------------------------
solo C4 3/8 38%
solo ADR 2/8 25%
solo arc42 3/8 38%
C4+ADR+arc42 8/8 100%
----------------------------------------
solo C4 deja SIN responder (5):
- Por que se eligio la cola en vez de escritura directa?
- Por que payments es un servicio aparte?
- Cuales son los atributos de calidad y sus metas?
- Cuales son las restricciones tecnicas del sistema?
- Que riesgos y deuda tecnica conocemos?
solo ADR deja SIN responder (6):
- Que hace el sistema y quien lo usa?
- De que piezas desplegables se compone?
- Como se estructura una pieza por dentro?
- Cuales son los atributos de calidad y sus metas?
- Cuales son las restricciones tecnicas del sistema?
- Que riesgos y deuda tecnica conocemos?
solo arc42 deja SIN responder (5):
- Que hace el sistema y quien lo usa?
- De que piezas desplegables se compone?
- Como se estructura una pieza por dentro?
- Por que se eligio la cola en vez de escritura directa?
- Por que payments es un servicio aparte?
Lee la tabla de cobertura primero, porque es el argumento de la lección en cuatro renglones.
Cada pieza sola deja la mayoría de las preguntas sin responder. El C4 solo responde 3 de 8 (38%): te muestra la estructura —qué hace el sistema, de qué piezas se compone, cómo se estructura una pieza por dentro— y nada más. Mira lo que deja sin responder: las dos preguntas de por qué (por qué la cola, por qué payments aparte) y las tres de calidad, restricciones y riesgos. Un dev nuevo con solo el C4 sabe cómo está armado Mercado, pero no por qué está armado así ni qué garantías debe cumplir —y ese por qué es justo lo que evita que "simplifique" una decisión sin entender su razón—. El ADR solo responde 2 de 8 (25%): te da los porqués, pero sin el mapa de la estructura ni los atributos de calidad, un dev nuevo tiene un montón de decisiones sueltas sin un mapa donde ubicarlas. Y arc42 "solo" —entendido como sus secciones de calidad, restricciones y riesgos— responde 3 de 8 (38%) pero deja sin responder la estructura y el porqué.
El combo responde las ocho: 100%. Y no es coincidencia ni redundancia —fíjate en que las coberturas no se solapan—: el C4 cubre las tres de estructura, el ADR las dos de porqué, y arc42 las tres de calidad/restricciones/riesgos. Cada pieza cubre una familia distinta de preguntas, y las tres familias juntas son lo que alguien necesita para entender un sistema de verdad: qué hay (C4), por qué está así (ADR), y qué debe cumplir y qué lo amenaza (arc42). Quitar cualquiera de las tres deja un hueco entero: sin C4, no hay mapa; sin ADR, no hay razones; sin las secciones de arc42, no hay atributos de calidad ni riesgos documentados. Por eso es un sistema y no una pila: cada pieza tiene su papel, y el valor está en la combinación.
Y el papel especial de arc42. Observa que arc42 aparece de dos formas en el ejemplo. Como contenido propio, cubre lo que ni el C4 ni el ADR traen —calidad, restricciones, riesgos—. Pero su papel más importante no está en la tabla de cobertura: arc42 es el esqueleto que le da un lugar a todo, incluidos el C4 y los ADRs. En la plantilla arc42, el C4 vive en las secciones de contexto y de vista de bloques de construcción; los ADRs viven en la sección de decisiones de arquitectura; y las preguntas de calidad, restricciones y riesgos tienen cada una su sección. arc42 no compite con el C4 y el ADR —los organiza—: es el archivador con pestañas donde el C4 va en una pestaña, los ADRs en otra, y hay pestañas para lo que faltaría. Por eso el sistema completo se llama "C4 + ADR + arc42": las dos primeras son contenido, la tercera es la estructura que las sostiene y muestra los huecos.
Como diagrama, el sistema se ve así:
arc42 = el esqueleto (el archivador con pestañas)
┌─────────────────────────────────────────────────────────────┐
│ arc42 │
│ ├─ Contexto y alcance ......... [ aqui va el C4-Context ] │
│ ├─ Vista de bloques ........... [ aqui va el C4-Container ] │
│ │ [ y el C4-Component ] │
│ ├─ Decisiones de arquitectura . [ aqui van los ADRs ] │
│ ├─ Objetivos de calidad ....... [ contenido propio arc42 ] │
│ ├─ Restricciones .............. [ contenido propio arc42 ] │
│ └─ Riesgos y deuda tecnica .... [ contenido propio arc42 ] │
└─────────────────────────────────────────────────────────────┘
El C4 muestra el QUE. El ADR guarda el POR QUE.
arc42 organiza ambos y añade lo que falta (calidad, restricciones, riesgos).
Profundización: por qué estas tres, y cómo se ensamblan
El experimento mostró que las tres piezas cubren familias de preguntas que no se solapan. Vale la pena entender por qué estas tres en particular forman el sistema que sobrevive, y cómo se ensamblan sin duplicarse.
Empecemos por lo que cada una hace bien y por qué es insustituible. El C4 documenta la estructura en niveles de zoom —Context, Container, Component, Code— y su fuerza es que es navegable: puedes empezar en el mapa del mundo (Context) y bajar hasta donde necesites, dándole a cada audiencia el nivel correcto (esto se enseñó a fondo en el módulo 3). Pero el C4 es deliberadamente mudo sobre el porqué: un diagrama muestra que payments está separado y que hay una cola, nunca por qué. Ese silencio no es un defecto —un diagrama que intentara explicar cada porqué sería ilegible—; es la razón por la que hace falta otra pieza. El ADR documenta el porqué de cada decisión significativa —contexto, decisión, consecuencias— y su fuerza es que el razonamiento viaja en el tiempo: el dev que dentro de dos años se pregunte "¿por qué payments no escribe directo al catálogo?" encuentra la respuesta en el ADR, y no deshace la decisión por ignorancia (su mecánica es la guía hermana architecture-decisions). Pero una colección de ADRs, sola, es un montón de decisiones sin un mapa que las ubique. Por eso el C4 y el ADR se necesitan mutuamente: el C4 es el mapa, el ADR es la leyenda de por qué el mapa es así.
Ahora, ¿por qué hace falta una tercera pieza, arc42? Porque hay conocimiento crítico que no es ni estructura ni una decisión puntual. Los atributos de calidad y sus metas ("payments debe procesar picos de X sin caerse", derivados en el módulo 5) no son un diagrama ni un ADR: son propiedades transversales del sistema entero. Las restricciones ("debemos usar el proveedor de nube que ya tenemos contratado", "cumplir tal regulación") condicionan todo pero no son una caja en un diagrama. Los riesgos y la deuda técnica conocida ("la instalación de sesiones en memoria no aguanta más de dos instancias", "sabemos que search necesita reescribirse") son conocimiento que salva a quien llega de tropezar con lo que ya sabíamos —pero que se pierde si no tiene un lugar—. arc42 aporta ese lugar: es una plantilla de doce secciones (contexto, restricciones, vista de bloques, vista de ejecución, decisiones, requisitos de calidad, riesgos, glosario, entre otras) donde cada tipo de conocimiento tiene su casilla. Su valor no es enseñar a dibujar ni a decidir —eso lo hacen el C4 y el ADR—; su valor es ser el esqueleto completo que garantiza que no se olvide ninguna dimensión, porque cada dimensión tiene una sección esperándola, y una sección vacía grita que falta algo.
De ahí sale el punto más importante sobre cómo se ensamblan: arc42 no reemplaza al C4 ni al ADR; los aloja. Un error común es pensar que hay que elegir entre C4, ADR y arc42, como si compitieran. No compiten: el C4 es el contenido de la sección de contexto y de vista de bloques de arc42; los ADRs son el contenido de la sección de decisiones de arc42; las secciones de calidad, restricciones y riesgos de arc42 se llenan a mano. El sistema completo es arc42 como estructura, con C4 y ADRs como parte de su contenido, más el contenido propio de las secciones que ellos no cubren. Escribir "documentación de arquitectura" es llenar ese esqueleto: no todas las secciones para todos los sistemas (un sistema chico no necesita las doce), pero sí las que importan, con la pieza correcta en cada una.
Un matiz honesto para no volver esto un culto a la plantilla. arc42 —o cualquier plantilla— es un andamio, no un fin. El objetivo no es "tener las doce secciones llenas"; es que las preguntas que la gente de verdad se hace tengan respuesta, y que las dimensiones importantes no se olviden. Un equipo chico con un sistema simple puede necesitar solo tres o cuatro secciones (contexto, decisiones clave, riesgos) y dejar el resto vacío o inexistente —y eso está bien—. El pecado no es dejar secciones vacías; el pecado es no tener el esqueleto y por eso olvidar una dimensión entera (documentar la estructura y el porqué, pero nunca los riesgos, porque no había un lugar que gritara su ausencia). Usa arc42 como el archivador que te recuerda qué pestañas podrías necesitar, no como una checklist burocrática que hay que llenar completa. Y recuerda las lecciones anteriores: todo esto vive en el repo (docs-as-code) y se documenta lo estable, no lo volátil (la próxima lección) —el esqueleto no cambia esas reglas, las organiza—.
Errores comunes
Confundir "un diagrama" con "la documentación" (solo C4). Qué pasa: el equipo dibuja un C4 bonito y lo considera "la documentación de arquitectura", sin ADRs ni las secciones de calidad y riesgos. Un dev nuevo entiende la estructura pero no por qué está así, y "simplifica" una decisión sin conocer su razón —reintroduciendo el problema que la decisión evitaba—. Por qué pasa: el diagrama es lo más visible y tangible de la doc, así que se confunde la parte con el todo. Cómo detectarlo: si tu doc responde "qué hay" y "cómo se conecta" pero no "por qué se decidió así" ni "qué debe cumplir", tienes solo el C4 —38% del sistema—. Cómo corregirlo: añadir los ADRs (el porqué) y las secciones de arc42 (calidad, restricciones, riesgos); el diagrama es una pieza del sistema, no el sistema.
Coleccionar ADRs sin un mapa (solo ADR). Qué pasa: el equipo escribe ADRs disciplinadamente —bien— pero no mantiene un C4 ni un esqueleto, así que hay treinta decisiones documentadas sueltas y ningún mapa donde ubicarlas. Un dev nuevo lee ADRs sin entender la estructura que modifican, como leer las actas de reuniones de una empresa sin el organigrama. Por qué pasa: los ADRs son fáciles de escribir uno por uno y dan sensación de progreso, pero sin la estructura que los contextualiza pierden la mitad de su valor. Cómo detectarlo: si tienes ADRs pero nadie puede señalar en un diagrama qué parte del sistema toca cada uno, te falta el mapa. Cómo corregirlo: mantener un C4 al día (el mapa) y organizar los ADRs dentro del esqueleto (arc42), de modo que cada decisión se pueda ubicar en la estructura que afecta.
Tratar arc42 como una checklist burocrática que hay que llenar completa. Qué pasa: el equipo adopta arc42 y siente que debe llenar las doce secciones, así que produce sección tras sección de contenido de relleno —vacío o volátil— para "completar la plantilla", y termina con un documento gigante que nadie lee (justo lo que la lección 7 del módulo 3 advertía). Por qué pasa: se confunde el andamio con el fin, y "todas las secciones llenas" se vuelve la meta en vez de "las preguntas importantes respondidas". Cómo detectarlo: si estás escribiendo secciones porque la plantilla las tiene y no porque alguien las vaya a leer, o si tu doc de arquitectura pesa 200 páginas, caíste en la burocracia. Cómo corregirlo: usar arc42 como recordatorio de qué dimensiones podrías necesitar, y llenar solo las que importan para tu sistema —dejar vacías o inexistentes las que no aplican—; el esqueleto sirve para no olvidar dimensiones, no para obligar a documentarlas todas.
Ejercicios
Ejercicio 1 — La pregunta que cada pieza no responde. Para cada una de estas tres preguntas sobre Mercado, di qué pieza del sistema (C4, ADR, o una sección de arc42) la responde, y por qué las otras dos no pueden: (a) "¿por qué payments está separado del núcleo?"; (b) "¿de qué contenedores desplegables se compone Mercado?"; (c) "¿qué pasa si el proveedor de pagos se cae —qué riesgo tenemos ahí?".
Ver solución
(a) "¿Por qué payments está separado?" → la responde el ADR. El C4 no puede: un diagrama muestra que payments está separado (una caja aparte), nunca por qué —un diagrama es mudo sobre el razonamiento—. arc42 tampoco, en sus secciones de calidad/restricciones/riesgos: esas describen propiedades y amenazas, no el porqué de una decisión puntual. Solo el ADR captura contexto + decisión + consecuencias, que es exactamente la forma de "por qué se decidió esto".
(b) "¿De qué contenedores se compone?" → la responde el C4 (nivel Container). El ADR no puede: los ADRs registran decisiones, no el inventario de la estructura —podrías leer todos los ADRs y no tener el mapa completo de piezas—. arc42 aloja el C4-Container en su sección de vista de bloques, pero el contenido que responde la pregunta es el diagrama C4. Solo el C4 da el mapa navegable de las piezas desplegables.
(c) "¿Qué riesgo hay si el proveedor de pagos se cae?" → la responde la sección de riesgos de arc42. El C4 no puede: muestra que hay una dependencia con el proveedor, pero no evalúa el riesgo de que falle. El ADR podría tocar el tema si hubo una decisión al respecto, pero el registro sistemático de "qué riesgos y deuda técnica conocemos" es justo la sección de riesgos de arc42 —el lugar designado para ese tipo de conocimiento, que sin un esqueleto se olvidaría—. Solo esa sección garantiza que el riesgo esté documentado y no viva solo en la cabeza de quien lo intuye.
El patrón: cada familia de preguntas tiene su pieza, y las otras no pueden suplirla porque están diseñadas para otra cosa. Por eso el sistema necesita las tres —quitar cualquiera deja una familia de preguntas sin respuesta—.
Ejercicio 2 — Por qué la cobertura no se solapa. En el ejemplo, el C4 cubre 3 preguntas, el ADR 2, arc42 3, y el combo exactamente 8 —la suma sin solapamiento—. Explica por qué es bueno que las coberturas no se solapen, y qué significaría (qué problema habría) si dos de las piezas respondieran las mismas preguntas.
Ver solución
Es bueno que no se solapen porque significa que cada pieza tiene un papel distinto e insustituible: el C4 es el único que responde la estructura, el ADR el único que responde el porqué, arc42 el único que responde calidad/restricciones/riesgos. Sin solapamiento, cada pieza añade cobertura que ninguna otra aporta, así que el sistema es eficiente —tres piezas, cero redundancia, 100% de cobertura— y quitar cualquiera deja un hueco identificable. Es la señal de un buen sistema de piezas complementarias: cada una hace algo que las demás no hacen.
Si dos piezas respondieran las mismas preguntas —digamos que tanto el C4 como los ADRs documentaran la estructura— habría un problema doble. Primero, redundancia: estarías manteniendo la misma información en dos lugares, lo que cuesta el doble de esfuerzo. Segundo, y peor, riesgo de desincronización: cuando la estructura cambiara, tendrías que actualizar los dos lugares, y tarde o temprano uno quedaría atrás del otro —el C4 diría una cosa y los ADRs otra—, y entonces nadie sabría cuál creer (justo el problema de confianza de la lección 2, ahora entre dos piezas de tu propia doc). Documentar la misma cosa dos veces viola el principio DRY (don't repeat yourself) aplicado a la doc: cada hecho debe tener un lugar donde vive, para que haya una fuente de verdad que mantener. Por eso el buen diseño del sistema de doc reparte las preguntas sin solapar: cada tipo de conocimiento tiene exactamente una pieza responsable, y esa pieza es la fuente de verdad para ese conocimiento.
Ejercicio 3 — Adaptar el esqueleto a un sistema chico. Un equipo de tres personas mantiene un servicio interno pequeño y simple. Su líder lee sobre arc42 y dice: "tenemos que documentar las doce secciones de arc42 para hacerlo bien". Otro responde: "no, arc42 es puro overhead, hagamos solo un README". Usando la idea del esqueleto como andamio (no como checklist), explica por qué ambos se equivocan y qué harías tú.
Ver solución
El primero se equivoca al tratar arc42 como una checklist que hay que llenar completa: para un servicio chico y simple, llenar las doce secciones produciría un documento gigante de puro relleno que nadie leería —cae en el error del documento de 500 páginas—. arc42 es un andamio que te recuerda qué dimensiones podrías necesitar, no una obligación de documentarlas todas; "hacerlo bien" no es tener las doce secciones, es que las preguntas importantes tengan respuesta.
El segundo se equivoca al descartar el esqueleto por completo y quedarse solo con un README: sin ningún esqueleto, es fácil olvidar una dimensión entera —por ejemplo, no documentar nunca por qué se tomaron las decisiones clave (sin ADRs) o los riesgos conocidos, porque no hay un lugar que grite su ausencia—. El valor del esqueleto no es la burocracia; es que las ausencias sean visibles. Un README solo responde "cómo lo corro y qué hace", pero no el porqué ni los riesgos.
Lo que yo haría: usar arc42 como guía de qué considerar, y llenar solo las secciones que importan para este sistema chico —probablemente cuatro: un contexto breve (qué hace y con qué habla, un C4-Context o incluso solo prosa), las decisiones clave (dos o tres ADRs para el porqué de lo importante), un README de onboarding (cómo correrlo), y una sección de riesgos/deuda conocida—. Las otras ocho secciones de arc42 (vista de ejecución detallada, glosario extenso, escenarios de calidad elaborados) se dejan fuera porque el sistema no las necesita. Así se obtiene lo mejor de los dos: la ligereza que pedía el segundo (no un documento gigante) y la garantía de no olvidar dimensiones que daba el esqueleto del primero. El esqueleto se adapta al tamaño del sistema; ni se ignora ni se llena completo por obligación. La regla: documenta lo que alguien va a leer y lo que dolería olvidar, y usa el esqueleto solo para no olvidar —no para llenar—.
Resumen y siguiente paso
En esta lección ensamblaste la documentación de arquitectura como un sistema, no como un artefacto suelto: el C4 (la estructura, el qué), el ADR (las decisiones, el por qué), y arc42 (el esqueleto que los organiza y añade calidad, restricciones y riesgos). Viste, con el archivador de pestañas contra la pila de papeles, que arc42 no compite con el C4 y el ADR sino que los aloja —cada tipo de conocimiento en su pestaña, y las ausencias visibles—. Y lo mediste: cada pieza sola responde entre 25% y 38% de las preguntas que un dev nuevo o un auditor hacen, con coberturas que no se solapan, mientras el combo responde el 100% —porque cada pieza cubre una familia distinta (estructura, porqué, calidad/riesgos) y las tres juntas son lo que alguien necesita—. Aprendiste que arc42 es un andamio que se adapta al tamaño del sistema, no una checklist que se llena completa, y que su valor es hacer visibles los huecos, no obligar a documentar todo.
Antes de avanzar deberías poder: decir qué familia de preguntas responde cada pieza (C4 el qué, ADR el porqué, arc42 la calidad/restricciones/riesgos); explicar por qué arc42 aloja al C4 y al ADR en vez de competir con ellos; y adaptar el esqueleto a un sistema chico sin llenarlo completo ni descartarlo.
La lección 5 responde la pregunta que este sistema deja abierta: ya sabes qué piezas componen la doc y dónde van, pero ¿qué información pones dentro de cada pieza y cuál dejas fuera? La respuesta es la regla que salva la doc del olvido: documentar lo estable, no lo volátil. Vas a ejecutar el ROI de documentar distintas cosas —los límites y las decisiones (estable) contra las listas de endpoints y las firmas (volátil)— y a descubrir que la variable que decide si documentar algo vale la pena no es su importancia, sino su volatilidad: lo volátil cuesta más mantenerlo que lo que rinde, y queda obsoleto antes de leerse. El sistema de esta lección solo sobrevive si lo llenas con lo estable; la próxima te enseña a distinguirlo.
Recursos
- arc42.org — la plantilla de doce secciones (Gernot Starke y Peter Hruschka) que es el esqueleto de esta lección. La documentación oficial explica qué va en cada sección y cómo el C4 y los ADRs encajan dentro. En inglés y alemán.
- Simon Brown — The C4 model (c4model.com) — el C4 como los niveles de estructura del sistema. En esta guía se enseñó a dibujarlo en el módulo 3; aquí es la pieza que responde el qué. En inglés.
- Michael Nygard — "Documenting Architecture Decisions" y adr.github.io — el ADR como la pieza que responde el por qué. Su mecánica es la guía hermana
architecture-decisions; aquí es un componente del sistema. En inglés. - Gernot Starke, Effective Software Architectures y el material de arc42 by example — ejemplos reales de arc42 llenado, útiles para ver cómo se aloja el C4 y los ADRs dentro del esqueleto y cómo se adapta al tamaño del sistema. En inglés.
- Stefan Zörner, Softwarearchitekturen dokumentieren und kommunizieren — un tratamiento a fondo de cómo combinar C4, ADR y arc42 en un sistema coherente de documentación (referencia clásica en el mundo arc42). En alemán, con ideas transversales.