Módulo 7: Documentación que sobrevive

8. Proyecto: haz que la documentación de Mercado sobreviva

Siguiente →

Descripción

En este proyecto vas a actuar como el arquitecto de Mercado y producir, de principio a fin, el paquete de documentación que sobrevive a un escenario real y urgente. No es una lección nueva: es donde ensamblas todo lo del módulo. El escenario tiene dos golpes a la vez, del tipo que cualquier equipo enfrenta tarde o temprano: Elena, la única persona que entiende el módulo de payments, avisó que se va en un mes; y al mismo tiempo, el equipo va a incorporar seis desarrolladores nuevos este trimestre para acelerar. Los dos golpes atacan lo mismo —el conocimiento—: la salida de Elena amenaza con llevarse el conocimiento de payments (bus factor 1), y la entrada de seis personas exige que el conocimiento del sistema esté disponible para que arranquen sin depender de nadie. Tu trabajo es dejar la documentación en un estado que sobreviva a los dos golpes, y probarlo con un reporte ejecutado.

Entregas cuatro cosas, cada una una pieza del módulo aplicada al caso: (1) la estructura docs-as-code —el esqueleto arc42 con el C4 y los ADRs, versionado en el repo, no en una wiki—; (2) el README que hace onboarding para los seis devs nuevos —que los lleve al primer commit sin depender de Elena ni de nadie—; (3) el ADR que captura la decisión estable de payments —el porqué de su diseño, escrito ahora que Elena está para dictarlo, para que sobreviva a su salida—; y (4) el reporte de listo-para-sobrevivir ejecutado: la doc validada contra el código, el bus factor de payments subido de 1 a 2, y el costo de onboarding con el nuevo README, terminando en un veredicto. Al final tendrás en tus manos exactamente lo que un arquitecto entrega cuando tiene que hacer que el conocimiento de un sistema sobreviva a una salida y a una ola de entradas.

Conexión con el módulo: este proyecto cierra los siete temas. Usa living documentation y docs-as-code (lecciones 2-3) para poner la doc en el repo y validarla; el sistema C4 + ADR + arc42 (lección 4) como estructura del paquete; la regla de documentar lo estable (lección 5) para elegir qué capturar de payments (su porqué, no sus detalles); el README que hace onboarding (lección 6) para los seis devs; y el bus factor (lección 7) como la métrica que mide si la salida de Elena deja huérfano payments. Al final, apunta al módulo 8: el capstone de la guía, donde serás el arquitecto de Mercado ante un cambio de negocio, y la documentación que sobrevive será parte de lo que entregues.

El expediente que le dejas al equipo antes de irte

Vuelve una vez más al dueño de casa —de los de ladrillo— pero en un momento particular: el día que se muda y le entrega la casa a los siguientes habitantes. Un buen dueño anterior no se va y ya; deja el expediente que permite que los nuevos operen la casa sin él: la carpeta con dónde está cada llave y cómo se prende cada cosa (para que puedan vivir en la casa desde el primer día), y una libreta con el porqué de las decisiones raras —"la cisterna está en el techo y no abajo porque la presión de la calle no alcanza; no la muevan sin resolver eso primero"— (para que no deshagan por ignorancia lo que él resolvió con cuidado). Se va, pero el conocimiento de cómo operar la casa y por qué está así se queda, escrito, disponible para cualquiera que llegue.

Tu paquete de documentación de Mercado es ese expediente de mudanza, con una diferencia de tiempo crucial: lo armas mientras Elena todavía está —mientras la abuela todavía puede dictar la receta—. La estructura docs-as-code y el README son la carpeta de "cómo se opera la casa" (para los seis que llegan); el ADR de payments es la libreta del "por qué está así" (para que nadie deshaga la decisión de Elena por no entenderla). Elena se irá, como el dueño anterior se muda; pero si el expediente está bien armado, el conocimiento de payments y de cómo arrancar Mercado se queda. Este proyecto es armar ese expediente y probar —con números— que de verdad permite operar la casa sin el dueño anterior.

El encargo: Elena se va, entran seis, y el conocimiento no puede irse con ella

El contexto, para que lo tengas claro antes de documentar. Mercado tiene seis módulos en el código: catalog, orders, payments, shipping, platform, search. Su mapa de conocimiento tiene dos puntos únicos de falla —payments (solo Elena) y search (solo Caro)—, pero el urgente es payments, porque Elena ya avisó que se va en un mes. Al mismo tiempo, entran seis devs nuevos que necesitan arrancar rápido. El arquitecto ya sabe qué hay que hacer a grandes rasgos: capturar lo estable de payments antes de que Elena se vaya, poner la doc en el repo donde no se pudra, y darles a los seis un README que los haga autónomos. Tu trabajo no es re-decidir eso: es producir el paquete y probar que deja la documentación lista para sobrevivir la salida de Elena.

Entregable 1: la estructura docs-as-code (el esqueleto en el repo)

Lo primero es dónde vive la doc: en el repo, junto al código, en texto plano, revisada en PRs y validada en CI —docs-as-code (lección 3)—, organizada con el esqueleto arc42 (lección 4). No en una wiki que se pudre. Así se ve la estructura en el repo:

mercado/
├─ src/                         <- el codigo (la fuente de verdad)
│   ├─ catalog/  orders/  payments/  shipping/  platform/  search/
├─ docs/                        <- la doc, versionada CON el codigo
│   ├─ README.md                <- onboarding (entregable 2)
│   ├─ architecture/            <- esqueleto arc42
│   │   ├─ 01-context.md         · C4-Context (el mapa del mundo)
│   │   ├─ 05-building-blocks.md · C4-Container (las piezas)
│   │   ├─ 09-decisions/         · los ADRs (el porque)
│   │   │   ├─ adr-014-*.md
│   │   │   └─ adr-030-payments-separate.md   <- entregable 3
│   │   ├─ 10-quality.md         · atributos de calidad y metas
│   │   └─ 11-risks.md           · riesgos y deuda (incl. bus factor)
│   └─ diagrams/                 <- PlantUML/Mermaid (texto, diffeable)
└─ .ci/
    └─ validate_docs.py          <- el validador (leccion 3): rompe el build

Fíjate en tres decisiones, cada una una lección del módulo. La doc vive en docs/, dentro del mismo repo que src/ (docs-as-code): el PR que cambia payments toca también su doc, y el revisor ve las dos cosas juntas —imposible que se desincronicen en silencio—. La estructura sigue arc42 (el esqueleto de la lección 4): cada tipo de conocimiento tiene su lugar —el C4 en contexto y bloques, los ADRs en decisiones, los riesgos en su sección— y las ausencias son visibles (una sección vacía grita que falta algo). Hay un validate_docs.py en CI (el validador de la lección 3): cruza lo que la doc afirma contra los módulos del código y rompe el build si hay una referencia rota o un módulo sin documentar. La doc no puede pudrirse en silencio, porque su sincronización es un test.

Entregable 2: el README que hace onboarding (para los seis que llegan)

Los seis devs nuevos necesitan arrancar sin depender de Elena. El README responde las cuatro preguntas de la lección 6 —qué hace, cómo correrlo, dónde están las piezas, cómo contribuir— con el "cómo correrlo" probado en máquina limpia:

# Mercado — Internal API

Marketplace que conecta compradores y vendedores. Este repo es la Internal API
(catalogo, pedidos, checkout, pagos, envios, busqueda).

## Como correrlo (probado en maquina limpia)
1. `cp .env.example .env`      # copia las variables; los secrets van en 1Password (ver #infra)
2. `docker compose up -d`      # levanta PostgreSQL, Redis y Elasticsearch
3. `make dev`                  # instala dependencias y corre la API en :8000
4. `make test`                 # corre los tests; deben pasar todos en verde
Si algo falla aqui, es un bug del README: avisa en #mercado-dev y lo arreglamos.

## Donde estan las piezas
Mapa completo en docs/architecture/05-building-blocks.md (C4-Container).
En una linea: catalog (productos) · orders (pedidos) · payments (cobros) ·
shipping (envios) · platform (auth, infra comun) · search (busqueda).

## Como contribuir
Rama -> PR -> review de un owner del modulo -> merge. CI corre tests Y valida la doc.
La doc de un modulo se actualiza en el MISMO PR que lo cambia (docs-as-code).

Cómo se lo cuentas a los seis: "Con esto arrancan solos. Sigan el 'cómo correrlo' tal cual; si un paso falla, no es que hicieron algo mal —es un bug del README y lo arreglamos, porque el README tiene que funcionar en máquina limpia—. El mapa de piezas les dice a dónde ir; el porqué de cada pieza está en los ADRs. Y ojo con la última regla: la doc de un módulo se actualiza en el mismo PR que lo cambia, para que no se pudra." Con este README, los seis llegan al primer commit útil en horas, sin consumir a nadie —y sin depender de Elena, que ya se va—.

Entregable 3: el ADR que captura la decisión estable de payments

Este es el entregable que compite contra el reloj: capturar el porqué de payments mientras Elena todavía está para dictarlo. Es lo estable (lección 5), lo que no está en el código, lo que más se pierde cuando alguien se va (lección 7). El ADR:

# ADR-030: Payments es un servicio separado, con cobro por cola

Status: Accepted | Fecha: 2026-07-30 | Deciden: Elena (owner de payments), arquitecto, lead de platform

## Contexto Payments cobra el dinero: es el módulo más delicado del sistema. Recibe tráfico del checkout (interno) y, a futuro, de vendedores externos. Un error o un pico que lo tumbe no solo pierde dinero: puede dejar cobros a medias, un estado corrupto que es carísimo de reconciliar. Además, la lógica de pagos tiene reglas de negocio y de cumplimiento (reembolsos, reintentos, idempotencia) que no deben mezclarse con el resto.

## Decisión Payments es un servicio separado del núcleo, con su propia frontera: nadie lee ni escribe sus tablas directamente; se habla con él por una interfaz clara. Los cobros no se procesan de forma síncrona en el checkout: se encolan y payments los procesa a su ritmo, con reintentos idempotentes, de modo que un pico del checkout no lo tumbe y un fallo no deje un cobro a medias.

## Consecuencias A favor:

  • El tráfico y los picos del checkout no pueden tumbar ni corromper payments: la cola amortigua y aísla.
  • Payments se puede escalar, proteger y auditar por separado, con sus reglas de cumplimiento contenidas.

En contra (el precio que aceptamos):

  • El cobro no es instantáneo: pasa por la cola, hay un retraso hasta la confirmación. Lo aceptamos porque la integridad del dinero vale más que la inmediatez.
  • Una pieza y una cola más que operar, y la complejidad de la idempotencia.

Este ADR es la libreta del "por qué está así" que Elena le deja al equipo. Cuando dentro de un año un dev nuevo —de los seis que llegan— vea la cola de payments y piense "esto sería más simple si el checkout cobrara directo", el ADR le dirá: sí, lo sabíamos; el retraso es el precio consciente de no dejar que un pico tumbe el dinero, y de no dejar cobros a medias. No deshará la decisión de Elena por ignorancia. El porqué —lo estable, lo que se iba a ir con Elena— se quedó escrito, dictado por ella mientras estaba. Esa es la receta de la abuela, capturada a tiempo.

Ejemplo trabajado: el reporte de listo-para-sobrevivir

Antes de dar el paquete por bueno, lo pasas por un reporte que mide las tres cosas que importan para el escenario: ¿la doc está sincronizada con el código (docs-as-code)? ¿el bus factor de payments deja de ser 1 cuando lo documentamos, de modo que la salida de Elena no lo deje huérfano? ¿el onboarding de los seis es barato con el nuevo README? El reporte corre las tres y da un veredicto:

# Proyecto: haz que la documentacion de Mercado SOBREVIVA. Escenario: Elena, unica
# conocedora de 'payments', se va en un mes; y entran 6 devs nuevos este trimestre.
# Producimos el reporte de listo-para-sobrevivir: (1) valida la doc contra el codigo,
# (2) mide el bus factor y a quien se lleva Elena, (3) mide el costo de onboarding
# con el nuevo README, y da un VEREDICTO.
CODE_MODULES = {"catalog", "orders", "payments", "shipping", "platform", "search"}
OWNERSHIP = {
    "catalog":  {"Ana", "Beto", "Caro"},
    "orders":   {"Beto", "Diego"},
    "payments": {"Elena"},
    "shipping": {"Diego", "Caro"},
    "platform": {"Ana", "Elena", "Beto"},
    "search":   {"Caro"},
}

# --- 1) La doc versionada en el repo, validada contra el codigo (docs-as-code) ---
DOC_REFERENCES = {
    "ADR-014":                   {"orders", "payments"},
    "ADR-030-payments-separate": {"payments", "orders", "platform"},
    "C4-container":              {"catalog", "orders", "payments", "shipping", "search"},
    "README":                    {"catalog", "orders", "payments", "shipping",
                                  "platform", "search"},
}
documented = set().union(*DOC_REFERENCES.values())
broken = sum(len(refs - CODE_MODULES) for refs in DOC_REFERENCES.values())
undocumented = CODE_MODULES - documented
doc_ok = (broken == 0 and not undocumented)
print("== 1) Doc-as-code: validacion contra el codigo ==")
print(f"  referencias rotas: {broken}")
print(f"  modulos sin documentar: {len(undocumented)}")
print(f"  -> {'PASA' if doc_ok else 'FALLA'}")

# --- 2) Bus factor y el punto unico de falla que Elena se llevaria ---
print("\n== 2) Bus factor antes de que Elena se vaya ==")
at_risk = [m for m, o in OWNERSHIP.items() if len(o) <= 1]
elena_orphans = [m for m, o in OWNERSHIP.items() if o - {"Elena"} == set()]
print(f"  modulos en riesgo (bus factor 1): {at_risk}")
print(f"  si Elena se va HOY, quedan huerfanos: {elena_orphans}")
STABLE_DOC = {"payments"}   # documentamos sus limites + la decision del ADR-030


def eff_bf(m):
    return len(OWNERSHIP[m]) + (1 if m in STABLE_DOC else 0)


print("  documentamos lo ESTABLE de 'payments' (ADR-030 + limites):")
print(f"    payments: bus factor {len(OWNERSHIP['payments'])} -> {eff_bf('payments')}")
elena_orphans_after = [m for m in elena_orphans if eff_bf(m) <= 1]
print(f"    si Elena se va ahora, huerfanos: {elena_orphans_after}")

# --- 3) Costo de onboarding de los 6 devs nuevos con el nuevo README ---
print("\n== 3) Onboarding de 6 devs nuevos con el README ==")
BLOCKERS = [
    ("correr el proyecto", 8.0, 0.5),
    ("ubicar las piezas",  6.0, 0.5),
    ("configurar entorno", 4.0, 0.25),
    ("correr los tests",   3.0, 0.25),
    ("donde cambiar",      5.0, 1.0),
    ("flujo de PR",        2.0, 0.1),
]
without = sum(w for _, w, _ in BLOCKERS)
with_ = sum(c for _, _, c in BLOCKERS)
NEW = 6
print(f"  tiempo al primer commit: sin README {without:.0f}h -> con README {with_:.1f}h")
print(f"  ahorro con {NEW} devs: {(without - with_) * NEW:.0f}h este trimestre")

# --- Veredicto ---
print("\n== VEREDICTO: lista para sobrevivir la salida de Elena? ==")
survives = doc_ok and not elena_orphans_after
print(f"  doc sincronizada con el codigo: {'si' if doc_ok else 'no'}")
print(f"  payments NO queda huerfano si Elena se va: {'si' if not elena_orphans_after else 'no'}")
print(f"  onboarding barato para los devs nuevos: si ({with_:.1f}h vs {without:.0f}h)")
print(f"  -> DOCUMENTACION {'SOBREVIVE' if survives else 'NO SOBREVIVE AUN'}")
print("  (pendiente honesto: 'search' sigue en bus factor 1 -> el proximo seguro)")

Qué esperar. Al correrlo, la salida es exactamente esta:

== 1) Doc-as-code: validacion contra el codigo ==
  referencias rotas: 0
  modulos sin documentar: 0
  -> PASA

== 2) Bus factor antes de que Elena se vaya ==
  modulos en riesgo (bus factor 1): ['payments', 'search']
  si Elena se va HOY, quedan huerfanos: ['payments']
  documentamos lo ESTABLE de 'payments' (ADR-030 + limites):
    payments: bus factor 1 -> 2
    si Elena se va ahora, huerfanos: []

== 3) Onboarding de 6 devs nuevos con el README ==
  tiempo al primer commit: sin README 28h -> con README 2.6h
  ahorro con 6 devs: 152h este trimestre

== VEREDICTO: lista para sobrevivir la salida de Elena? ==
  doc sincronizada con el codigo: si
  payments NO queda huerfano si Elena se va: si
  onboarding barato para los devs nuevos: si (2.6h vs 28h)
  -> DOCUMENTACION SOBREVIVE
  (pendiente honesto: 'search' sigue en bus factor 1 -> el proximo seguro)

Lee el reporte sección por sección, porque cada una es una pieza del módulo probada sobre el caso.

Sección 1: la doc pasa la validación. Cero referencias rotas y cero módulos sin documentar —a diferencia del validador de la lección 3, que fallaba, aquí el paquete que armaste está sincronizado: cada cosa que la doc afirma existe en el código, y cada módulo del código (incluido platform, que en la lección 3 estaba sin documentar) tiene doc—. La doc está en el repo, validada en CI, en verde. Docs-as-code cumplido: la doc no se va a pudrir en silencio.

Sección 2: el bus factor de payments deja de ser 1. El reporte confirma el diagnóstico: payments y search están en bus factor 1, y si Elena se va hoy, payments queda huérfano. Luego aplica el entregable 3 —documentar lo estable de payments (el ADR-030 y sus límites)—, y el bus factor de payments sube de 1 a 2. Ahora, si Elena se va, la lista de huérfanos es vacía: []. Ese es el corazón del proyecto medido: la salida de Elena ya no deja payments sin dueño, porque su conocimiento estable se capturó a tiempo. La receta se escribió mientras la abuela estaba.

Sección 3: el onboarding de los seis es barato. Con el README del entregable 2, el tiempo hasta el primer commit útil baja de 28h a 2.6h por dev, y con los seis que entran eso son 152 horas ahorradas este trimestre —casi un mes-persona que, sin README, se quemaría en descubrir el sistema a golpes—. Los seis arrancan solos, sin depender de Elena que se va ni de nadie.

El veredicto: DOCUMENTACIÓN SOBREVIVE. Las tres condiciones se cumplen —doc sincronizada, payments no huérfano si Elena se va, onboarding barato— así que el paquete deja a Mercado listo para sobrevivir la salida de Elena y la entrada de los seis. Pero fíjate en la última línea, y es deliberada: el pendiente honesto —search sigue en bus factor 1—. El veredicto es sobre sobrevivir la salida de Elena específicamente (el golpe urgente), no sobre eliminar todo riesgo. search, que solo mantiene Caro, sigue siendo un punto único de falla, y el siguiente seguro que hay que comprar es documentar lo estable de search antes de que Caro se vaya. Un arquitecto honesto no declara "todo resuelto"; declara "resuelto el golpe urgente, y aquí está el siguiente riesgo en la fila". Esa honestidad —medir lo que se logró y nombrar lo que falta— es parte del oficio.

Errores comunes

Documentar payments en pánico el último día (tarde). Qué pasa: el equipo espera a que Elena esté por irse y, en su última semana, intenta extraerle todo el conocimiento de payments en sesiones apuradas de traspaso. Sale incompleto: Elena ya tiene un pie afuera, el conocimiento tácito no aflora bajo presión, y lo que se documenta es de baja calidad. Por qué pasa: mientras Elena estaba, documentar payments no parecía urgente (ella sabía), así que se pospuso hasta que fue urgente y ya casi tarde. Cómo detectarlo: si la documentación de un módulo crítico se está haciendo después del aviso de salida de su único dueño, ya vas tarde. Cómo corregirlo: capturar lo estable de los módulos en bus factor 1 ahora, mientras sus dueños están en plena forma y usan el conocimiento a diario —la prima del seguro se paga antes de la salida (lección 7), no en la última semana—.

Poner la doc en una wiki "para compartirla con los seis" (lejos del código). Qué pasa: pensando en los seis devs nuevos, el equipo escribe la doc en una wiki bonita "para que sea fácil de encontrar y compartir", separada del repo. Se pudre exactamente como en las lecciones 2 y 3, y para cuando el segundo grupo de devs llega, la doc ya miente. Por qué pasa: la wiki parece más "compartible" y presentable que archivos Markdown en el repo. Cómo detectarlo: si tu paquete de onboarding vive fuera del repo, no puedes validarlo ni revisarlo en los PRs, y se va a desincronizar. Cómo corregirlo: la doc vive en el repo (docs-as-code); se "comparte" igual de bien (los seis clonan el repo y ahí está todo), y además se mantiene viva por proximidad y validación. La comodidad de la wiki es la trampa que el módulo entero desmonta.

Declarar "todo resuelto" y ocultar el pendiente (deshonestidad). Qué pasa: el equipo asegura payments, ve el veredicto SOBREVIVE, y reporta "la documentación de Mercado está resuelta" —ocultando que search sigue en bus factor 1—. Meses después Caro se va, search queda huérfano, y nadie lo vio venir porque el reporte dijo "todo bien". Por qué pasa: es más cómodo (y se ve mejor) reportar un éxito completo que un éxito parcial con un pendiente. Cómo detectarlo: si tu reporte no nombra explícitamente los riesgos que no resolviste, estás ocultando el siguiente golpe. Cómo corregirlo: todo veredicto honesto nombra su alcance y su pendiente —"resuelto el riesgo de Elena/payments; sigue abierto el de Caro/search, y es el próximo seguro a comprar"—; el bus factor es un radar que hay que dejar encendido, no apagar tras el primer arreglo. Un arquitecto reporta lo que logró y lo que falta.

Ejercicios

Ejercicio 1 — Arma el paquete para el siguiente riesgo. El reporte dejó un pendiente honesto: search sigue en bus factor 1 (solo Caro). Como arquitecto, arma el esqueleto del paquete para asegurar search antes de que Caro se vaya: (a) ¿qué entregable del módulo es el más urgente y por qué?; (b) ¿qué decisión de search merecería un ADR?; (c) ¿cómo lo verificarías con el reporte?

Ver solución

(a) El entregable más urgente es el ADR que captura lo estable de search (su porqué y sus límites), hecho mientras Caro todavía está. Es lo mismo que con payments: lo estable (el porqué, la frontera) es lo que no está en el código, lo que más se pierde cuando Caro se va, y lo que sube el bus factor de 1 a 2 barato (lección 7). Y es urgente por la misma razón temporal: hay que escribir la receta mientras la abuela está, no en su última semana. El README y la estructura docs-as-code ya existen del paquete anterior; lo que falta específicamente para search es capturar su conocimiento estable.

(b) La decisión de search que merecería un ADR: por ejemplo, "por qué search usa un índice separado (Elasticsearch) en vez de consultar directo la base de datos" —una decisión con trade-off real (el índice da búsqueda rápida y relevante pero añade una pieza que hay que sincronizar y que puede quedar desactualizada respecto a la base)—. O "cómo se mantiene sincronizado el índice con el catálogo, y qué pasa si se desincroniza". Cualquiera que tenga un porqué con precio que un dev futuro querría entender antes de cambiarlo. Ese porqué es justo lo que se iría con Caro si no se escribe.

(c) Cómo lo verificaría con el reporte: correría el mismo reporte de listo-para-sobrevivir, pero simulando la salida de Caro en vez de Elena, y con STABLE_DOC = {"payments", "search"} (ahora los dos documentados). Esperaría ver: search en la lista de riesgo baja a bus factor 2 tras documentarlo; "si Caro se va, huérfanos: []"; y el veredicto SOBREVIVE también para la salida de Caro. Con los dos módulos asegurados, el sistema completo dejaría de tener puntos únicos de falla —el bus factor del sistema subiría de 1 a 2 (lección 1)—. El reporte es la forma de probar que el nuevo seguro funciona, no solo afirmarlo.

Ejercicio 2 — Detecta el paquete mal armado. Un colega te pasa su paquete para el mismo escenario (Elena se va, entran seis): documentó payments a fondo en una wiki de Confluence con 40 páginas que incluyen cada endpoint y cada firma de función; no escribió ningún ADR ("los diagramas lo explican todo"); y no tocó el README ("los seis pueden preguntarle al equipo cómo arrancar"). Sin correr código, diagnostica qué está mal usando las lecciones del módulo, y di cómo lo reharías.

Ver solución

Diagnóstico:

  • Wiki en Confluence, lejos del código (lecciones 2-3): la doc separada del repo se va a pudrir —no se puede revisar en los PRs ni validar en CI, así que se desincronizará release a release hasta que nadie confíe en ella—. Además, no es docs-as-code: no hay validador que rompa el build si la doc miente.
  • 40 páginas con cada endpoint y firma (lección 5): documentó lo volátil a fondo. Los endpoints y las firmas cambian todo el tiempo (churn alto, ROI negativo); esas 40 páginas quedarán obsoletas en semanas. Gastó el esfuerzo en lo que menos sobrevive.
  • Ningún ADR (lecciones 4-5-7): no capturó el porqué de payments —lo estable, lo que no está en el código, lo que más se pierde cuando Elena se va—. "Los diagramas lo explican todo" es falso: un diagrama muestra el qué, nunca el por qué. Justo lo que se iba a ir con Elena quedó sin capturar.
  • README sin tocar (lección 6): "que le pregunten al equipo" mantiene el onboarding dependiente de personas —consume al equipo y no sube el bus factor del conocimiento operativo—. Los seis tardarán 28h cada uno en arrancar, y dependiendo de gente.

Cómo lo rehago: invierto las prioridades. (1) Muevo la doc al repo (docs/), en Markdown, validada en CI —docs-as-code—. (2) Borro las 40 páginas de endpoints y firmas volátiles; eso se genera del código (OpenAPI) o se lee ahí. (3) Escribo el ADR de payments —su porqué y sus límites, lo estable— con Elena, ahora que está: es lo urgente y lo que sube el bus factor. (4) Escribo el README con el "cómo correrlo" probado, para que los seis arranquen solos. (5) Corro el reporte de listo-para-sobrevivir para probar que payments no queda huérfano y que el onboarding es barato. El paquete pasa de "40 páginas volátiles en una wiki que se pudre, sin porqué y sin onboarding" a "lo estable en el repo, validado, con el porqué capturado y los seis autónomos" —de mucha doc que no sobrevive a poca doc que sí—.

Ejercicio 3 — El guion de la conversación con Elena. Tienes una semana con Elena antes de que se vaya, y su tiempo es escaso (está cerrando pendientes). Escribe, en cuatro o cinco frases, el guion de cómo usas ese tiempo para capturar lo que de verdad importa de payments —aplicando la regla de lo estable vs lo volátil— sin desperdiciar su última semana en lo que se puede recuperar de otra forma.

Ver solución

Un guion que aprovecha el tiempo escaso de Elena enfocándolo en lo estable e irrecuperable:

  1. Le pido a Elena el porqué, no el qué. "Elena, no necesito que me expliques cada función de payments —eso lo leo del código—. Necesito que me expliques las decisiones: por qué está separado, por qué la cola en vez de cobro directo, qué problemas resolviste que no son obvios." (Enfoco su tiempo en lo estable que no está en el código y que se iría con ella.)
  2. Escribimos juntos el ADR-030 mientras hablamos. "Vamos a escribir esto ahora, aquí, en un ADR en el repo —tú dictas el porqué y las consecuencias, yo tecleo—; así queda tu razonamiento en tus palabras, versionado, para siempre." (Capturo el porqué a tiempo, docs-as-code.)
  3. Le pregunto por los sustos —lo tácito. "¿Qué es lo que te da miedo que alguien toque en payments sin entender? ¿Qué parece un bug pero es a propósito? ¿Dónde están los cables sueltos?" (Saco el conocimiento tácito —los trucos de la abuela— que solo aflora preguntando, y lo anoto en el ADR y en la sección de riesgos.)
  4. NO gasto su tiempo en listar endpoints, firmas ni configuración. Eso es volátil y se recupera del código; pedírselo a Elena sería malgastar su última semana en lo que menos importa y menos sobrevive.
  5. Cierro validando que un dev nuevo pueda seguir el rastro. "Dejo el ADR enlazado desde el README y el C4, para que el próximo que toque payments encuentre el porqué antes de cambiar nada." (Conecto el porqué capturado con el onboarding de los seis.)

La clave: la última semana de Elena es un recurso escasísimo, y se gasta en lo estable e irrecuperable —el porqué, los sustos, lo tácito—, no en lo volátil que se lee del código. Escribir la receta con la abuela es preguntarle lo que solo ella sabe y no está en ningún lado, no pedirle que copie a mano lo que ya está escrito en la cocina.

Resumen: qué construiste y hacia dónde sigue

En este proyecto armaste el paquete de documentación que sobrevive a un escenario real —Elena se va en un mes, entran seis devs— aplicando todo el módulo. Produjiste la estructura docs-as-code (el esqueleto arc42 con C4 y ADRs en el repo, validado en CI, no en una wiki), el README que hace onboarding (para que los seis arranquen solos, con el "cómo correrlo" probado), y el ADR-030 que captura la decisión estable de payments —su porqué, escrito mientras Elena estaba para dictarlo, para que sobreviva a su salida—. Y probaste el paquete con el reporte de listo-para-sobrevivir: la doc pasa la validación (sincronizada con el código), el bus factor de payments sube de 1 a 2 (ya no queda huérfano si Elena se va), y el onboarding baja de 28h a 2.6h por dev (152h ahorradas). El veredicto: DOCUMENTACIÓN SOBREVIVE —con el pendiente honesto nombrado: search sigue en bus factor 1, el próximo seguro—. Ese es el entregable real de un arquitecto que hace que el conocimiento sobreviva: no una wiki enorme, sino lo estable en el repo, validado, con el porqué capturado a tiempo y la gente nueva autónoma, medido y con su pendiente a la vista.

Con esto cierras el módulo 7. Ya sabes documentar de forma que el conocimiento sobreviva: entender por qué la doc se pudre y qué la mantiene viva, ponerla en el repo con docs-as-code y validarla en CI, ensamblar el sistema C4 + ADR + arc42, documentar lo estable y no lo volátil, escribir el README que hace onboarding, y medir y subir el bus factor para que el sistema no dependa de una sola cabeza.

Hacia dónde sigue. El módulo 8 es el capstone de toda la guía: tomarás el rol del arquitecto de Mercado ante un cambio de negocio real —abrir Mercado a vendedores externos por API y crecer 10x— y recorrerás todo el oficio de una vez: derivarás los atributos de calidad desde la meta (módulo 5), aplicarás la maniobra inversa de Conway para estructurar los equipos (módulo 2), producirás el C4 y el ADR que comunican la decisión (módulo 3), explicarás el trade-off al stakeholder (módulo 5), planearás la evolución (módulo 6) —y documentarás todo de forma que sobreviva (este módulo)—. La documentación que sobrevive no es un añadido al final; es lo que hace que todo el trabajo del arquitecto —las decisiones, los límites, el porqué— perdure más allá de quien lo hizo. El capstone junta las piezas; esta fue la que garantiza que no se pierdan.

Recursos

← AnteriorBus factor y compartir conocimientoSiguiente →1. Presentación del capstone: el oficio como un solo movimiento