Lección 48 — Documentación y ADRs

Stack: Docs as code · Proyecto: TicketFlow Estado: Publicada — apertura del módulo de habilidades no técnicas Prerrequisito: Lección 47 — Depurar en producción

Objetivos

1. Distinguir los tipos de documentación (tutorial, how-to, referencia, explicación — Diátaxis) y elegir el formato por lector.
2. Escribir ADRs que registren las decisiones del curso (ya tomaste 10+ en los ejercicios): contexto, decisión, consecuencias, revisión.
3. Mantener la documentación viva con docs-as-code: en el repo, en el PR, con caducidad y test donde se pueda.

1. Los cuatro formatos y su lector

La matriz de Diátaxis (el mapa que evita el "doc de todo"): tutorial (enseña a un principiante: el curso mismo, el onboarding del repo — "haz esto paso a paso, aprenderás"), how-to (resuelve el problema de alguien que ya sabe: "cómo añadir un endpoint con problem+json" — receta, no clase), referencia (la consulta seca: la API del 15, la tabla de eventos del 45, los settings del 27 — exactitud, cero narración), explicación (el porqué: los ADRs, los postmortems del 47, esta lección). El error clásico: el README que mezcla las cuatro (500 líneas que nadie navega). El test: ¿qué pregunta del lector responde este doc? — "¿cómo empiezo?" (tutorial), "¿cómo hago X?" (how-to), "¿qué significa este campo?" (referencia), "¿por qué es así?" (explicación). Cada pregunta merece SU doc, enlazado.

docs/
  onboarding.md        # tutorial: día 1 en el repo
  howtos/              # how-to: una receta por fichero
    nuevo-endpoint.md
    rotar-secreto.md   # la checklist del 27
  reference/           # referencia: API (15), eventos (45), runbooks (47)
  adr/                 # explicación: las decisiones, §2
  postmortems/         # explicación: el 47

2. El ADR: la unidad mínima de memoria técnica

El ADR (Architecture Decision Record) registra UNA decisión irreversible-cara de revertir. El formato del curso (el que los ejercicios vienen pidiendo):

# ADR-0011 — Broker de eventos: Redis Streams
Fecha: 2027-09-20 · Estado: aceptado · Decide: backend · Supersede: —
## Contexto
~150k eventos/día; equipo de 1; Redis ya operado (12); la saga del 32 exige orden por agregado.
## Decisión
Outbox (25) → Redis Streams con consumer groups; Celery-Redis para tareas (comandos).
## Consecuencias
+ Cero infra nueva, PEL para reclamos, replay básico.
− Retención corta; el replay masivo exige export por día.
## Revisión
Reevaluar si el volumen ×10 o la saga exige retención semanal (el trigger escrito: el ADR con
fecha de caducidad implícita vive; el sin trigger muere en el drawer).

Las 5 claves del formato: UNA decisión por ADR (el ADR de 3 decisiones decide ninguna bien); el contexto con NÚMEROS (el volumen que justifica); las consecuencias con + y − (la honestidad: toda decisión pierde algo); el trigger de revisión (el ADR vivo se reabre cuando el mundo cambió, no cuando alguien discute por gusto); y el Supersede: (el ADR-0018 que reemplaza al 0011 lo enlaza: la historia de decisiones es una cadena, no un fichero que se edita — los ADRs NO se corrigen, se reemplazan).

3. Los ADRs que este curso ya tomó (el índice)

La revisión del curso produce el índice de decisiones (cada una con su lección):

El índice (el fichero docs/adr/README.md) es el mapa del porqué del sistema: el compañero nuevo lee 12 ADRs de una página y entiende el sistema en una hora (vs 3 meses de folklore). Y el test de la decisión documentada: cuando alguien pregunta "¿por qué Redis y no Kafka?", la respuesta es un enlace, no una anécdota.

4. Docs-as-code: en el repo, en el PR, con caducidad

La documentación fuera del repo (wiki, Google Doc, la mente) diverge en semanas. Las reglas del proyecto: (1) los docs viven en docs/ del repo (markdown, revisados en PR como el código — la 44 lo demostró con la infra, aquí con el texto); (2) el doc de cada PR: si el PR cambia el contrato (13/14), la referencia de la API se regenera (drf-spectacular del 15: la doc que NO se actualiza a mano es la única que sobrevive); (3) los docs con fecha y dueño (Última revisión: 2027-09-28, buffy) y el runner del 31: la revisión trimestral de docs (el doc sin revisión en 6 meses se marca "posiblemente podrido" — la caducidad explícita vence al silencio); (4) lo testable se testea: el doc que dice "los listados no traen total" YA es test de contrato (39) — el doc que puede ser código, ES código.

<!-- el patrón de doc-enlazada-al-código -->
La disponibilidad que decide la compra NUNCA se cachea (ver ADR-0006 y el test
test_disponibilidad_no_cacheada_en_checkout) — si este test muere, este doc miente.

5. La documentación como habilidad del oficio

Lo que la documentación compra (medido en este curso): el onboarding (el ADR índice: 1 h vs 3 meses), el incidente (el runbook del 47: MTTR −40%), el futuro-tú (el postmortem de hace 4 meses explica el sistema de hoy), y la revisión de decisiones (el trigger del ADR evita tanto la moda como el fósil). La regla del esfuerzo: documenta la decisión cuando la TOMAS (10 min en el PR) — el doc post-hoc nunca se escribe. Y la honestidad final: la doc podrida es PEOR que la ausente (el lector confía y se equivoca); por eso la caducidad (§4) y la referencia generada del código (15) son las dos únicas garantías de verdad.

Autoevaluación

1. Los 4 formatos de Diátaxis: ¿qué pregunta responde cada uno y cuál es el error del README de todo?
2. ¿Qué 5 claves tiene el ADR del curso y por qué los ADRs se reemplazan (Supersede) y no se editan?
3. El índice de ADRs del curso: ¿qué compra el índice que las lecciones sueltas no?
4. ¿Qué significa docs-as-code en este proyecto y qué dos mecanismos garantizan que la doc no pudra?
5. ¿Por qué documentar la decisión AL TOMARLA (10 min) vence a "lo documento cuando esté estable"?

Continúa con los ejercicios. Las solutions.md solo tras intentarlo.