Lección 48 — Documentación y ADRs

La memoria del proyecto, escrita. Sin solutions.md hasta entregar.

Ejercicio 1 — El mapa de docs

1. Audita TU documentación actual: ¿qué formato tiene cada doc (tutorial/how-to/referencia/explicación)? ¿Cuál mezcla todo en un README de 500 líneas?
2. Reorganiza (o diseña) el docs/ con la estructura del §1: los 4 directorios, 2 docs mínimos por directorio (el how-to "nuevo-endpoint" y la referencia de eventos son obligatorios).
3. El test del lector: para cada doc nuevo escribe en la PR la pregunta del lector que responde ("¿cómo hago X?"). Si un doc responde a 3 preguntas: divídelo.

Ejercicio 2 — Los ADRs del curso

1. Escribe los 3 ADRs que más te hayan marcado del índice (§3) en el formato completo (contexto con números, decisión, consecuencias +/−, trigger de revisión, Supersede si aplica).
2. El índice: crea docs/adr/README.md con la tabla de decisiones del curso (las 12 del §3 + las tuyas) — cada fila enlaza al ADR y a la lección que lo originó.
3. La cadena de Supersede: simula el cambio de decisión (¿Kafka por volumen ×10?): escribe el ADR-0018 que reemplaza al 0011 (contexto nuevo, decisión nueva, el enlace al viejo con su estado "superseded"). ¿Qué pasa con el viejo (¿se borra? ¿se edita? la respuesta está en el §2).

Ejercicio 3 — La referencia viva

1. La referencia de eventos del 45: conviértela en la fuente de verdad documentada (tabla evento/claves/nivel/emisor) y añade el test que la valida: el catálogo de eventos del código y el doc deben coincidir (test que lee ambos y falla si divergen — el doc-enlazado-al-código del §4).
2. La API: verifica que la referencia de la 15 (drf-spectacular) se regenera en el pipeline del 41 y que el doc enlaza al schema generado (jamás copiado a mano).
3. El settings del 27: la referencia de variables de entorno generada DESDE el settings (el.env.example como fuente) — ¿cómo evitas que el doc y el código diverjan? Implementa el mecanismo (test o generación).

Ejercicio 4 — La caducidad

1. Añade la cabecera de revisión a TODOS tus docs (Última revisión, dueño) y la tarea trimestral del 31 (o el check del CI: el doc sin revisión en 6 meses marca warning en el build — implementable con un script de 20 líneas).
2. El doc-enlazado-al-código: elige 2 afirmaciones de tus docs que PUEDEN ser tests ("los listados no traen total" del 39, "la disponibilidad no se cachea en checkout" del 38) y crea los tests que las guardan. El doc queda enlazado al test por nombre.
3. El README del repo: reescríbelo con la matriz de Diátaxis: 30 líneas máximo con los 4 enlaces (onboarding, howtos, referencia, ADRs) — la puerta, no la casa.

Ejercicio 5 — El onboarding

1. Escribe el docs/onboarding.md (tutorial del día 1): clonar → compose del 40 → seed → el primer test en verde → el tour de los ADRs. El test del tutorial: ¿un compañero (o tú en máquina limpia) termina el día 1 con el sistema corriendo y un PR hecho?
2. La prueba real: sigue TU onboarding en un entorno limpio (o simúlalo paso a paso): ¿cuántos pasos faltaban? Arregla el doc con lo que descubriste (el doc que no se prueba es ficción).
3. El cierre del módulo: la lista de "las 5 documentaciones que más te sirvieron del curso" (¿el runbook del 47? ¿el ADR del 43? ¿el.env.example del 27?) — la regla personal de qué documentas primero cuando el tiempo aprieta.

Entrega

Pega la estructura de docs/, 3 ADRs completos, el test doc↔código y el onboarding probado. Después: Lección 49 — Estimar y dividir problemas.