Presentación del módulo: documentación que sobrevive

Por qué este módulo existe aquí

Hay una pregunta que casi ningún equipo se hace hasta que ya es tarde: si mañana se va la persona que más sabe de este sistema, ¿cuánto se va con ella? La respuesta honesta, en la mayoría de los equipos, es "demasiado". No porque nadie haya escrito documentación —casi siempre hay una wiki, o un Confluence, o una carpeta de Google Docs—, sino porque esa documentación no sobrevive: se escribió una vez, quedó desconectada del código, se fue desincronizando de la realidad, y hoy nadie la abre porque nadie confía en ella. Cuando la persona que sí sabe se va, el conocimiento se va con ella, y el equipo descubre a golpes lo que el sistema hace. Este módulo es sobre lo contrario: documentar de forma que el conocimiento sobreviva al tiempo, al recambio de personas y al onboarding del que llega.

Esta guía completa enseña el oficio humano y organizacional de ser arquitecto. En el módulo 1 desmontaste el mito del rol. En el 2 viste cómo la organización moldea el sistema (Conway). En el 3 aprendiste a comunicar con el C4 y el ADR. En el 4, a liderar sin autoridad. En el 5, a traducir metas de negocio en atributos de calidad. En el 6, a diseñar para el cambio. Todos esos módulos produjeron conocimiento: decisiones, límites, trade-offs, el porqué de cada cosa. Y todos descansaban sobre un supuesto que nunca dijeron en voz alta: que ese conocimiento se queda. No se queda solo. Vive en las cabezas de las personas, y las personas se van. Este módulo instala la disciplina que evita que el conocimiento se vaya con ellas: la documentación que sobrevive.

Y aquí hay que ser preciso con la frontera del ecosistema, porque este módulo toca dos herramientas que ya viste. El C4 —los cuatro niveles de zoom de un diagrama— se enseñó a fondo en el módulo 3 de esta misma guía: cómo dibujarlo, qué nivel para qué audiencia. El ADR —el registro de una decisión de arquitectura— viene de la guía hermana architecture-decisions-and-tradeoffs: su mecánica, cómo se escribe, cómo se clasifica una decisión. Este módulo no re-enseña ninguna de las dos. Aquí el C4 y el ADR son piezas de un sistema de documentación que tiene que durar: no "cómo dibujo un Container" (eso es M3) ni "cómo redacto un ADR" (eso es la otra guía), sino "cómo hago que el C4 y el ADR de Mercado sigan siendo ciertos y útiles dentro de dos años, cuando la mitad del equipo sea otra". El módulo enseña el principio y el criterio de la documentación que sobrevive, no las herramientas específicas a fondo.

El caso, mirado desde el conocimiento: Mercado y la cabeza que se puede ir

Mercado es el marketplace que nos acompaña toda la guía, y aquí lo miramos con una lente nueva: el conocimiento. No el diagrama del sistema, sino el mapa de quién sabe qué. Recuerda su organización —cinco squads que trabajan sobre cinco módulos: catalog, orders, payments, shipping, platform—. Detrás de cada módulo hay personas concretas que lo entienden, que pueden arreglarlo un domingo a las 3 a. m. cuando algo se cae, que saben por qué está hecho como está.

Ese mapa esconde un riesgo que ningún diagrama de arquitectura muestra. Mira las personas que sostienen cada módulo:

Mapa de conocimiento de Mercado (quien puede mantener cada modulo)

  catalog   ── Ana, Beto, Caro        (3 conocedores)
  orders    ── Beto, Diego            (2 conocedores)
  payments  ── Elena                  (1 conocedor)  <-- una sola cabeza
  shipping  ── Diego, Caro            (2 conocedores)
  platform  ── Ana, Elena, Beto       (3 conocedores)

catalog lo sostienen tres personas; platform, tres. Si una se va, quedan dos. Pero payments —el módulo que cobra el dinero, el más delicado del sistema— lo mantiene una sola persona: Elena. Si Elena se va de vacaciones dos semanas, nadie puede tocar payments con confianza. Si Elena se va de la empresa, ese módulo queda huérfano: nadie más sabe por qué está hecho como está, qué decisiones lo sostienen, dónde están los cables sueltos. Ese es un punto único de falla de conocimiento, y no aparece en ningún C4, en ningún organigrama, en ninguna métrica de rendimiento. Aparece solo el día que Elena presenta su renuncia —cuando ya es tarde—.

El arquitecto de Mercado no arregla esto pidiéndole a Elena que no se vaya. Las personas se van: es lo normal, no una emergencia. Lo arregla haciendo que el conocimiento de Elena no dependa solo de Elena. Y la forma más barata de hacerlo no es clonar a Elena (formar un segundo experto humano cuesta semanas), sino documentar lo estable de payments —sus límites, sus decisiones, el porqué de su diseño— de modo que esa doc actúe como un "conocedor que nunca se va". La doc no reemplaza a Elena; pero deja de ser Elena el único seguro. Ese es el oficio de este módulo, y —como todo en esta guía— se puede medir.

Conexión con el módulo. Esta es la lección-mapa. No entra a fondo en ninguna de las piezas; instala la tesis (la mayoría de la doc no sobrevive; documentar bien es escribir lo estable, cerca del código, para subir el bus factor), el vocabulario (living documentation, docs-as-code, bus factor, doc estable vs volátil, el combo C4+ADR+arc42, el README de onboarding) y el mapa de cómo cada lección construye la disciplina. La lección 2 explica por qué la doc se pudre y qué la mantiene viva. La 3 enseña docs-as-code: la doc en el repo, revisada en PRs, validada en CI. La 4 ensambla el sistema C4 + ADR + arc42. La 5 marca la regla que salva la doc: documentar lo estable, no lo volátil. La 6 escribe el README que hace onboarding. La 7 va al corazón: el bus factor y compartir conocimiento. Y la 8 te pone a hacer que la documentación de Mercado sobreviva ante un caso real, ejecutado. Cuidado con la frontera: el C4 como diagrama es el módulo 3 y el ADR como mecánica es architecture-decisions; aquí ambos son piezas de un sistema de doc que debe durar.

Y la promesa de siempre: aunque el tema parece "escribir texto", lo cuantificable se ejecuta, no se afirma. Cada simulación corre con Python 3.14 y solo la biblioteca estándar, con datos fijos, así que la salida de cada bloque "Qué esperar" es la salida literal de correr el código. Puedes copiarlo y reproducirlo idéntico.

Una analogía: el manual que el dueño anterior te dejó (o no)

Piensa en el día que te mudas a una casa que no construiste —la compraste o la rentaste—, y en dos versiones de ese día.

La casa sin manual. Llegas, y no hay nada. Nadie te dejó una nota. Así que empiezas a descubrir la casa a golpes: es de noche y no encuentras el interruptor de la sala, tanteas la pared media hora. En invierno el agua sale helada y no sabes cómo se prende el boiler —¿es de gas?, ¿dónde está el piloto?—, hasta que un plomero te cobra una visita para señalarte una perilla. Se corta la luz de la cocina y no sabes cuál de los veinte breakers es, así que los apagas todos y los vas probando. Un día se inunda el patio y no encuentras la llave de paso del agua para cerrarla —está enterrada detrás de unas macetas que el dueño anterior puso encima—. Cada cosa que la casa hace, la aprendes por sufrimiento, semana tras semana, y algunas nunca las aprendes: hay una válvula en el techo que no sabes para qué sirve y prefieres no tocar. La casa funciona, pero tú vives peleándote con ella porque el conocimiento de cómo opera se fue con el dueño anterior.

La casa con manual. Llegas, y en la cocina hay una carpeta que el dueño anterior te dejó: "Bienvenido. La llave de paso general del agua está en el jardín, detrás del rosal, tapa verde. El boiler es de gas: perilla a la izquierda del garaje, el piloto se prende con el encendedor que está colgado al lado. El breaker de la cocina es el tercero de arriba, etiquetado. La válvula del techo es del calentador solar; no la toques en invierno." En diez minutos sabes operar la casa. No descubres nada a golpes: el dueño anterior destiló lo que aprendió en años y te lo entregó en una página. Cuando se corta la luz de la cocina, vas directo al breaker correcto. Cuando se inunda el patio, cierras la llave en treinta segundos. No es que la casa sea mejor —es la misma casa—; es que el conocimiento de cómo opera sobrevivió al cambio de dueño.

Esa carpeta es la documentación que sobrevive de este módulo, y la analogía tiene tres capas que vale la pena separar, porque son tres lecciones distintas:

• La carpeta existe y es cierta (living documentation, docs-as-code): de nada sirve un manual que dice "el boiler es eléctrico" cuando en realidad es de gas —peor: te manda por el camino equivocado—. El manual tiene que estar sincronizado con la casa real. Si el dueño anterior cambió el boiler y no actualizó la nota, la nota se volvió una trampa. La doc que sobrevive vive pegada a la realidad y se actualiza cuando la realidad cambia (lecciones 2 y 3).
• La carpeta documenta lo estable, no lo volátil (lección 5): el manual útil dice dónde está la llave de paso (eso no se mueve en años) y por qué la válvula del techo no se toca en invierno (una decisión con su porqué). No dice "hoy la sala está pintada de azul" —eso cambia, y un manual que intenta seguirle el paso a lo que cambia cada mes está siempre equivocado—.
• La carpeta te permite operar sin llamar al dueño anterior (README de onboarding, bus factor): el valor del manual es que no necesitas al dueño anterior. Puedes operar la casa sin su número de teléfono. Si además el manual sobrevive a que tú te mudes y se lo dejas al siguiente, el conocimiento nunca depende de una sola persona (lecciones 6 y 7).

El sistema de software es igual. El módulo de payments de Mercado es la casa; Elena es el dueño anterior que sabe dónde está cada llave. La pregunta del módulo es: cuando Elena se mude, ¿le dejó al equipo la carpeta —el manual que le permite operar payments sin llamarla— o el equipo va a descubrir payments a golpes, cable por cable, decisión por decisión? Este módulo entrena escribir esa carpeta, y —lo más importante— escribir la que sobrevive, no la que se pudre en un cajón.

Ejemplo trabajado: el bus factor de Mercado, y cómo la doc lo sube

Empecemos por poner número al riesgo del que hablamos: el bus factor. El nombre viene de una pregunta brutal —"¿cuántas personas del equipo tendrían que ser atropelladas por un autobús para que el proyecto no pueda seguir?"—. En su forma útil, el bus factor de un módulo es cuántas personas tendrían que irse para que ese módulo quede huérfano: sin nadie que sepa mantenerlo. Un módulo que conocen tres personas tiene bus factor 3 (tendrían que irse las tres); uno que conoce una sola persona tiene bus factor 1 —y ese es el peligroso, porque una sola salida lo deja sin dueño—. El bus factor del sistema es el mínimo entre sus módulos: lo fija el eslabón más débil.

Vamos a calcularlo sobre el mapa de conocimiento de Mercado, y luego a ver qué le pasa cuando documentamos lo estable del módulo más débil:

# Bus factor: cuantas personas tendrian que irse para que un modulo quede
# HUERFANO (sin nadie que sepa mantenerlo). El bus factor de un modulo es el
# numero de personas que hoy lo conocen; el del SISTEMA es el minimo entre modulos:
# el eslabon mas debil. Un modulo con bus factor 1 es un punto unico de falla:
# si esa sola persona se va, el modulo queda sin dueno.
OWNERSHIP = {
    # modulo -> personas que hoy pueden mantenerlo
    "catalog":  ["Ana", "Beto", "Caro"],
    "orders":   ["Beto", "Diego"],
    "payments": ["Elena"],
    "shipping": ["Diego", "Caro"],
    "platform": ["Ana", "Elena", "Beto"],
}


def bus_factor(module, doc=False):
    # Una doc ESTABLE del modulo (sus limites y decisiones) actua como un
    # "conocedor que nunca se va": suma 1 al bus factor.
    return len(OWNERSHIP[module]) + (1 if doc else 0)


print(f"{'modulo':<10}{'conocedores':>13}{'bus factor':>12}{'estado':>22}")
print("-" * 57)
for m in OWNERSHIP:
    bf = bus_factor(m)
    estado = "PUNTO UNICO DE FALLA" if bf == 1 else "ok"
    print(f"{m:<10}{len(OWNERSHIP[m]):>13}{bf:>12}{estado:>22}")
print("-" * 57)
system_bf = min(bus_factor(m) for m in OWNERSHIP)
weakest = min(OWNERSHIP, key=lambda m: bus_factor(m))
print(f"Bus factor del SISTEMA: {system_bf}  (lo fija el modulo mas debil: {weakest})")
print()
print("Documentamos 'payments' (sus limites y decisiones: lo ESTABLE):")
bf_before = bus_factor("payments")
bf_after = bus_factor("payments", doc=True)
print(f"  payments: bus factor {bf_before} -> {bf_after}")
new_system_bf = min(bus_factor(m, doc=(m == "payments")) for m in OWNERSHIP)
print(f"  Bus factor del SISTEMA: {system_bf} -> {new_system_bf}")
print("La doc no reemplaza a la persona, pero deja de ser el UNICO seguro:")
print("payments ya no queda huerfano si Elena se va.")

Qué esperar. Al correr el archivo, la salida es exactamente esta:

modulo      conocedores  bus factor                estado
---------------------------------------------------------
catalog               3           3                    ok
orders                2           2                    ok
payments              1           1  PUNTO UNICO DE FALLA
shipping              2           2                    ok
platform              3           3                    ok
---------------------------------------------------------
Bus factor del SISTEMA: 1  (lo fija el modulo mas debil: payments)

Documentamos 'payments' (sus limites y decisiones: lo ESTABLE):
  payments: bus factor 1 -> 2
  Bus factor del SISTEMA: 1 -> 2
La doc no reemplaza a la persona, pero deja de ser el UNICO seguro:
payments ya no queda huerfano si Elena se va.

Lee la tabla despacio, porque contiene el argumento entero del módulo.

Primero, el diagnóstico. Cuatro de los cinco módulos están sanos: catalog y platform con bus factor 3, orders y shipping con 2. Pero payments tiene bus factor 1, y la tabla lo marca: PUNTO ÚNICO DE FALLA. Y aquí está el detalle que asusta: el bus factor del sistema no es el promedio de los módulos ni el del más fuerte —es el del más débil—. Aunque cuatro de cinco módulos estén bien acompañados, el sistema completo tiene bus factor 1, porque basta con que se vaya una persona (Elena) para que un módulo crítico (payments) quede huérfano. El sistema es tan resiliente como su eslabón más débil, y el eslabón más débil de Mercado es una sola cabeza.

Segundo, la cura. Documentamos lo estable de payments —no cada detalle volátil, sino sus límites y sus decisiones: por qué está separado, qué contratos expone, qué reglas de negocio lo gobiernan—. Esa doc actúa como un conocedor más, uno que no se va nunca: cualquier persona nueva puede leerla y ponerse al día. El bus factor de payments sube de 1 a 2, y con eso el bus factor del sistema entero sube de 1 a 2. Con un solo acto de documentación —el más barato posible, porque documentamos lo que no cambia— eliminamos el punto único de falla del sistema completo.

Fíjate en la frase final del programa, porque evita un malentendido importante: "la doc no reemplaza a la persona, pero deja de ser el único seguro". Documentar payments no vuelve a Elena prescindible ni la reemplaza como experta —Elena sigue siendo quien mejor conoce el módulo y quien lo evoluciona—. Lo que la doc hace es que su conocimiento deje de morir con su salida. Antes, Elena era el único seguro contra perder payments; ahora hay dos: Elena y la doc de lo estable. Si Elena se va, el módulo no queda huérfano —queda con un manual—. Ese es exactamente el rol de la documentación que sobrevive: no sustituir a las personas, sino evitar que el sistema dependa de que una persona en particular nunca se vaya.

Y observa algo sobre el costo: subimos el bus factor documentando lo estable. Si hubiéramos intentado subirlo documentando cada detalle volátil de payments —cada función, cada endpoint, cada valor de configuración—, esa doc se pudriría en semanas (payments cambia esos detalles seguido) y volvería a valer 1. Documentar lo estable es barato de mantener y barato de subir el bus factor, porque lo estable, por definición, no cambia mucho. Esa es la conexión entre el bus factor (lección 7) y la regla de lo estable vs lo volátil (lección 5), y por eso el módulo las enseña juntas.

Las seis piezas de la disciplina

Ese ejemplo tocó, sin desarrollarla, la tesis del módulo. Cada lección instala una pieza de la disciplina de documentar para que el conocimiento sobreviva. Vale la pena verlas juntas, porque son la columna vertebral de las siete lecciones que siguen.

1. Living documentation: por qué la doc se pudre y qué la mantiene viva (lección 2). La primera pieza: entender por qué la mayoría de la documentación fracasa —se desconecta del código y se pudre— y qué significa que esté viva: pegada al código, actualizada en el mismo cambio que la vuelve obsoleta. Se mide el abismo de confianza: cuando la exactitud cae bajo un umbral, la doc entera vale cero aunque parte siga correcta.

2. Docs-as-code: la doc en el repo, revisada en PRs (lección 3). La práctica concreta que fuerza la proximidad: escribir la doc en Markdown/PlantUML, versionarla junto al código, revisarla en los mismos PRs y validarla en CI. La lección ejecuta un validador que detecta doc desincronizada y rompe el build, convirtiendo "la doc se pudrió" de un problema invisible en un test rojo.

3. El sistema C4 + ADR + arc42 (lección 4). La documentación que sobrevive no es una pieza suelta, es un sistema: el C4 muestra la estructura, el ADR guarda el porqué, y arc42 es el esqueleto que los organiza y cubre lo que falta. La lección mide la cobertura de cada pieza sola (insuficiente) contra el combo (completo).

4. Documentar lo estable, no lo volátil (lección 5). La regla que salva la doc del olvido: documentar lo que cambia poco (los límites, las decisiones) y no lo que cambia cada semana (la lista de endpoints, las firmas). La lección mide el ROI: lo volátil cuesta más de lo que rinde y queda obsoleto antes de leerse.

5. El README que hace onboarding (lección 6). El primer contacto del dev nuevo: qué hace el sistema, cómo correrlo, dónde están las piezas. La lección mide el costo de onboarding —el tiempo hasta el primer commit útil— con README y sin él.

6. Bus factor y compartir conocimiento (lección 7). El corazón: no depender de una sola cabeza. La lección simula quién se va y qué queda huérfano, y compara los seguros para subir el bus factor —la doc de lo estable resulta el más barato—.

Guarda este mapa; es la ruta del módulo:

Pieza de la disciplina               Leccion   La idea en una frase
──────────────────────────────────  ────────  ─────────────────────────────────────
Living documentation                 L2        la doc viva vive pegada al codigo
Docs-as-code                         L3        la doc en el repo, un test que rompe
El sistema C4 + ADR + arc42          L4        tres piezas, un sistema de doc
Documentar lo estable, no lo volatil L5        documenta lo que no cambia
El README que hace onboarding        L6        el primer commit util en horas
Bus factor y compartir conocimiento  L7        que no dependa de una sola cabeza
──────────────────────────────────  ────────  ─────────────────────────────────────
Haz que la doc de Mercado sobreviva  L8        el mini-proyecto, ejecutado

El mapa: dónde está este módulo en la guía y en el ecosistema

Este módulo es el penúltimo de la guía, y cierra el arco del oficio con la dimensión del conocimiento que perdura. Así se conecta con el resto:

flowchart TD
    M1["M1 · Que hace de verdad un arquitecto"]
    M2["M2 · La ley de Conway"]
    M3["M3 · Comunicar la arquitectura (C4)"]
    M4["M4 · Liderazgo tecnico sin autoridad"]
    M5["M5 · Stakeholders y atributos de calidad"]
    M6["M6 · Disenar para el cambio"]
    M7["M7 · Documentacion que sobrevive<br/>(el conocimiento que perdura)"]
    M8["M8 · Proyecto: ser el arquitecto de<br/>Mercado ante un cambio"]
    M1 --> M2 --> M3 --> M4 --> M5 --> M6 --> M7 --> M8

Léelo así: en los módulos 1 a 6 instalaste el rol, la dinámica org↔sistema, la comunicación, el liderazgo, la traducción de metas a atributos y la postura ante el cambio. Aquí, en M7, agregas la dimensión que hace que todo eso perdure: el conocimiento que produjiste —las decisiones, los límites, el porqué— tiene que sobrevivir al tiempo y al recambio de personas, o se pierde. En M8 harás todo el recorrido como arquitecto de Mercado ante un cambio real, y la documentación que sobrevive será parte de lo que entregues.

Y la frontera con el resto del ecosistema, que hay que respetar con cuidado. El C4 —cómo dibujar cada nivel, qué diagrama para qué audiencia— es el módulo 3 de esta guía; no lo re-enseñamos, lo usamos como una pieza del sistema de doc. El ADR —cómo se redacta, cómo se clasifica una decisión, la mecánica— es la guía hermana architecture-decisions-and-tradeoffs; tampoco lo re-enseñamos, lo usamos como el registro del porqué que sobrevive. Cuando en la lección 4 hablemos del "combo C4 + ADR + arc42", no vamos a enseñar a dibujar un Container ni a redactar un ADR (eso ya lo sabes); vamos a enseñar cómo esas piezas se ensamblan en un sistema que dura —y qué añade arc42 para que no queden huecos—. La distinción de siempre en esta guía: las herramientas contra el oficio de mantenerlas vivas.

Errores comunes

Estos tres errores son las tres formas de fallar frente a la supervivencia del conocimiento que el módulo entero combate. Aparecen aquí en su forma de resumen; cada lección abre uno a fondo.

La wiki que se pudre (documentar lejos del código). Qué pasa: el equipo escribe documentación en una wiki desconectada del código —Confluence, Notion, una carpeta de Docs—, la actualiza una vez, y luego el código sigue cambiando mientras la wiki se queda quieta. En pocos meses la wiki está tan desincronizada que nadie confía en ella, y todos vuelven a preguntarle a la persona que sí sabe: la doc existe pero no sirve. Por qué pasa: escribir la doc lejos del código es más cómodo en el momento (no requiere tocar el repo), pero rompe el único mecanismo que la mantiene viva —actualizarla en el mismo cambio que la vuelve obsoleta—. Cómo detectarlo: si tu doc vive en un sistema separado del código, si nadie la abre para trabajar, o si la respuesta a "¿esto está documentado?" es "sí, pero seguro está desactualizado", tu wiki se está pudriendo. Cómo corregirlo: mover la doc al repo, junto al código, y revisarla en los mismos PRs —docs-as-code—, de modo que la proximidad la fuerce a mantenerse viva. La lección 2 mide el abismo: una wiki al 20% de exactitud vale cero, porque nadie confía en ella.

Documentar de más lo volátil y de menos lo estable. Qué pasa: el equipo, con buena voluntad, intenta documentar todo —cada función, cada endpoint, cada valor de configuración—, y como esos detalles cambian todo el tiempo, la doc queda obsoleta en semanas; mientras tanto, lo que de verdad sobreviviría —las decisiones, los límites, el porqué— queda sin documentar porque no alcanzó el tiempo. Por qué pasa: se confunde "documentar bien" con "documentar mucho", y lo volátil es lo más tentador de documentar porque es lo más concreto y visible. Cómo detectarlo: si tu doc describe firmas de funciones o listas de endpoints que cambian cada sprint, pero no explica por qué payments está separado ni cuáles son sus límites, estás documentando lo volátil y olvidando lo estable. Cómo corregirlo: documentar lo estable (decisiones y fronteras, que cambian poco) y dejarle lo volátil al código o a la generación automática. La lección 5 lo mide: lo volátil tiene ROI negativo —cuesta más mantenerlo que lo que rinde—.

El conocimiento en una sola cabeza (bus factor 1). Qué pasa: un módulo crítico lo entiende una sola persona, y el equipo lo acepta como normal —"pregúntale a Elena, ella sabe de payments"— hasta el día que esa persona se va (de vacaciones, de equipo, de empresa) y el módulo queda huérfano: nadie sabe por qué está hecho como está ni cómo tocarlo sin romperlo. Por qué pasa: es cómodo. Mientras la persona está, tener el conocimiento concentrado en ella es eficiente —no hay que documentar nada, se le pregunta y ya—; el costo solo aparece cuando se va, y para entonces es tarde. Cómo detectarlo: si hay módulos que "solo fulano entiende", si el equipo entra en pánico cuando esa persona se va de vacaciones, o si un módulo tiene bus factor 1, tienes conocimiento en una sola cabeza. Cómo corregirlo: subir el bus factor documentando lo estable de esos módulos —el seguro más barato— y complementar con pairing o rotación para el conocimiento vivo. La lección 7 lo mide: documentar lo estable es 7.5 veces más barato que formar un segundo dueño humano, y elimina el punto único de falla.

Ejercicios

Ejercicio 1 — El bus factor del sistema. El mapa de conocimiento de Mercado tiene cuatro módulos con bus factor 2 o 3 y uno (payments) con bus factor 1. Un gerente mira eso y dice: "el sistema está bien documentado, cuatro de cinco módulos tienen respaldo; el bus factor del sistema es bueno". Usando la definición del ejemplo, explica por qué el gerente se equivoca, y cuál es de verdad el bus factor del sistema.

Ver solución

El gerente se equivoca porque promedia (o mira la mayoría) cuando el bus factor del sistema no es un promedio: es el mínimo entre los módulos, porque el sistema es tan resiliente como su eslabón más débil. Que cuatro de cinco módulos tengan bus factor 2 o 3 no ayuda si el quinto —payments, además el que cobra el dinero— tiene bus factor 1: basta con que se vaya una persona (Elena) para que ese módulo crítico quede huérfano, y con él, el sistema no puede seguir operando con confianza. El bus factor del sistema de Mercado es 1, no "bueno". El error del gerente es de agregación: cree que la salud del conjunto es el promedio de las partes, cuando en realidad la fija la parte más débil.

La consecuencia práctica: para subir el bus factor del sistema no hay que trabajar en los módulos que ya están bien (subir catalog de 3 a 4 no cambia nada), sino en el cuello de botella —payments—. Documentar lo estable de payments sube su bus factor de 1 a 2, y con eso el del sistema entero de 1 a 2. La regla del oficio: para mejorar el bus factor del sistema, ataca siempre el módulo más débil, no el promedio.

Ejercicio 2 — Las tres capas del manual. La analogía del manual que el dueño anterior te dejó tenía tres capas: (a) que el manual exista y sea cierto, (b) que documente lo estable y no lo volátil, (c) que te permita operar sin llamar al dueño anterior. Traduce cada capa a un problema concreto del módulo de payments de Mercado, y di qué lección del módulo lo trabaja.

Ver solución

(a) Que el manual exista y sea cierto → living documentation / docs-as-code (lecciones 2 y 3). El problema concreto: de nada sirve una doc de payments que dice "cobra con el proveedor X por escritura directa" cuando en realidad ya se migró a una cola y a otro proveedor —esa doc no solo no ayuda, engaña al dev nuevo, como el manual que dice que el boiler es eléctrico cuando es de gas—. La doc de payments tiene que estar sincronizada con el código real y actualizarse cuando payments cambia; eso se logra teniéndola pegada al código (living) y en el repo revisada en PRs (docs-as-code).

(b) Que documente lo estable y no lo volátil → documentar lo estable (lección 5). El problema concreto: si la doc de payments intenta listar cada endpoint y cada valor de configuración (volátil), quedará obsoleta en semanas; lo que debe documentar es lo estable —por qué payments está separado del núcleo, qué contratos expone, qué reglas de negocio lo gobiernan—, que es lo que no cambia y lo que un dev nuevo de verdad necesita, igual que el manual dice dónde está la llave de paso (estable) y no de qué color está pintada la sala hoy (volátil).

(c) Que te permita operar sin llamar al dueño anterior → README de onboarding y bus factor (lecciones 6 y 7). El problema concreto: el valor de la doc de payments es que un dev nuevo pueda entender y tocar el módulo sin llamar a Elena. Si cada duda sobre payments termina en "pregúntale a Elena", la doc no cumplió su función y el bus factor sigue siendo 1. La doc que sobrevive es la que hace innecesaria la llamada al dueño anterior —y así el conocimiento deja de depender de una sola cabeza—.

Ejercicio 3 — Barato porque estable. En el ejemplo, subimos el bus factor de payments documentando lo estable (sus límites y decisiones), no cada detalle. Explica por qué documentar lo estable es a la vez barato de mantener y efectivo para subir el bus factor, y qué pasaría si en cambio intentáramos subir el bus factor documentando cada detalle volátil de payments.

Ver solución

Documentar lo estable es barato de mantener por definición: lo estable es lo que cambia poco —por qué payments está separado, qué límites tiene, qué decisiones lo sostienen no cambia release a release—, así que la doc de lo estable casi no requiere actualizaciones y se mantiene cierta durante años con poco esfuerzo. Y es efectivo para subir el bus factor porque lo que un dev nuevo necesita para no dejar huérfano el módulo no es la lista de cada función (eso lo lee del código), sino el mapa mental: por qué está hecho así, dónde están las fronteras, qué decisiones no debe deshacer sin entender el porqué. Ese mapa mental es justo lo estable, y es lo que actúa como "el conocedor que nunca se va".

Si en cambio intentáramos subir el bus factor documentando cada detalle volátil de payments —cada endpoint, cada firma, cada valor de configuración—, pasarían dos cosas malas a la vez. Primero, esa doc se pudriría en semanas, porque payments cambia esos detalles seguido y nadie alcanzaría a mantenerla sincronizada; en poco tiempo estaría desactualizada, nadie confiaría en ella, y el bus factor volvería a 1 (una doc en la que no se confía vale cero, como veremos en la lección 2). Segundo, habríamos gastado un esfuerzo enorme en lo que menos sobrevive y menos importa para el mapa mental, dejando probablemente sin documentar lo estable que sí cuenta. El resultado: mucho trabajo, doc podrida, bus factor sin mejorar. Por eso la regla —documenta lo estable, no lo volátil— no es solo sobre eficiencia: es lo que hace que la doc sobreviva y que el bus factor se quede arriba.

Resumen y siguiente paso

En esta lección instalaste la tesis que sostiene todo el módulo: la mayoría de la documentación no sobrevive —se pudre en una wiki desconectada— y documentar bien no es escribir mucho, sino escribir lo que perdura. Viste el caso de Mercado desde el conocimiento: el mapa de quién sabe qué esconde un punto único de falla que ningún diagrama muestra —payments lo mantiene una sola persona, Elena, bus factor 1—. Lo mediste: el bus factor del sistema lo fija el módulo más débil, así que aunque cuatro de cinco módulos estén bien acompañados, el sistema entero tiene bus factor 1; y documentar lo estable de payments lo sube de 1 a 2, eliminando el punto único de falla con el acto de documentación más barato posible. Con la analogía del manual que el dueño anterior te dejó, separaste las tres capas de la doc que sobrevive: que exista y sea cierta, que documente lo estable, y que te permita operar sin llamar al dueño anterior.

Antes de avanzar deberías poder: explicar por qué el bus factor del sistema es el mínimo (no el promedio) de sus módulos; traducir las tres capas del manual a problemas concretos de payments; y argumentar por qué documentar lo estable es a la vez barato de mantener y efectivo para subir el bus factor.

La lección 2 toma la primera pieza de la disciplina y la desarrolla a fondo: living documentation —por qué la doc se pudre y qué la mantiene viva—. Vas a ver, con números, por qué una wiki desconectada del código se desincroniza hasta que nadie confía en ella, y a ejecutar el abismo de confianza: el momento en que la exactitud cae bajo un umbral y la doc entera vale cero, aunque parte siga siendo correcta. Con eso entenderás por qué la única doc que sobrevive es la que vive pegada al código —y por qué la comodidad de la wiki es una trampa—.

Recursos

• Cyrille Martraire, Living Documentation: Continuous Knowledge Sharing by Design (Addison-Wesley, 2019) — el libro central del módulo. Su tesis es exactamente la de esta guía: la documentación que sobrevive es la que vive pegada al código y a las decisiones, no la que se escribe aparte y se pudre. En inglés.
• arc42.org — la plantilla de documentación de arquitectura (Gernot Starke y Peter Hruschka) que la lección 4 usa como esqueleto del sistema de doc. Doce secciones que organizan el C4, los ADRs y lo que falta (calidad, restricciones, riesgos). En inglés y alemán.
• Simon Brown — The C4 model (c4model.com) — el C4 como sistema de diagramas por nivel. En esta guía se enseñó a dibujarlo en el módulo 3; aquí se usa como pieza de la documentación que sobrevive. En inglés.
• Michael Nygard — "Documenting Architecture Decisions" (2011) y adr.github.io — el ADR como el porqué que viaja en el tiempo. Su mecánica es la guía hermana architecture-decisions; aquí el ADR es el registro estable que sobrevive al recambio de personas. En inglés.
• Write the Docs — la comunidad y la idea de docs-as-code — la práctica de tratar la documentación como código: en el repo, en texto plano, revisada en PRs, validada en CI. La base de la lección 3. En inglés.
• Martin Fowler — Software Architecture Guide — el hub para seguir profundizando en por qué la arquitectura importa y cómo comunicarla y documentarla; buen puente hacia el resto del ecosistema. En inglés.