Módulo 7: Documentación que sobrevive
Living documentation
Descripción
La lección anterior instaló la tesis con una medición: el conocimiento de un sistema vive en cabezas que se van, y la documentación que sobrevive es el seguro contra eso. Pero ahí hay una trampa que esta lección desmonta: la mayoría de la documentación no sobrevive, aunque se escriba. No porque nadie la escriba —casi siempre hay una wiki—, sino porque se pudre: se escribe una vez, queda desconectada del código, y a medida que el código cambia y la wiki se queda quieta, la doc se va desincronizando de la realidad hasta que dice cosas falsas. Y una doc que dice cosas falsas es peor que no tener doc: manda al dev nuevo por el camino equivocado. Esta lección explica por qué la doc se pudre, y qué significa la alternativa: living documentation —documentación viva, que se mantiene cierta porque vive pegada al código y a las decisiones, y se actualiza en el mismo cambio que la volvería obsoleta—.
El concepto de living documentation, que popularizó Cyrille Martraire, tiene una idea central sencilla: la doc que sobrevive es la que está tan cerca del código que actualizarla es parte de cambiar el código, no un paso aparte que alguien recordará hacer después. La wiki desconectada se pudre porque actualizarla es un acto separado —requiere acordarse, abrir otra herramienta, escribir— y "después" nunca llega. La doc viva no se pudre porque no hay un "después": el cambio y su documentación viajan juntos. Esta lección mide la diferencia entre las dos a lo largo de la vida de un sistema, y descubre un fenómeno que hace la trampa aún peor de lo que parece: el abismo de la confianza. Cuando la exactitud de una doc cae bajo cierto umbral, los devs dejan de confiar en toda ella —no pueden saber qué parte sigue bien y qué parte ya es falsa—, así que su valor efectivo se desploma a cero aunque una fracción siga siendo correcta. La doc no se degrada suave; cae por un acantilado.
Conexión con el módulo. Es la primera de las lecciones que instalan cómo hacer que la doc sobreviva. Aquí trabajamos el principio —qué mantiene viva la doc: la proximidad al código—; la lección 3 trabajará la práctica concreta que fuerza esa proximidad (docs-as-code: la doc en el repo, revisada en PRs). Es la relación entre entender por qué el manual del dueño anterior tiene que estar sincronizado con la casa (esta lección) y el mecanismo que lo garantiza —pegarlo a la pared de la casa, no dejarlo en otra ciudad— (la siguiente). Frontera con el resto: aquí no re-enseñamos a dibujar el C4 ni a redactar un ADR; hablamos de qué hace que cualquier artefacto de doc —un diagrama, un ADR, un README— siga siendo cierto con el tiempo.
Una analogía: la etiqueta en la máquina contra el manual en el sótano de otro edificio
Piensa en una fábrica con una máquina complicada —una prensa, un horno industrial— y en dos maneras de documentar cómo operarla de forma segura.
El manual en el sótano de otro edificio. La empresa escribió, hace años, un manual grueso y completo de la máquina: cada procedimiento, cada advertencia, cada válvula. Lo imprimió, lo encuadernó, y lo guardó en un archivo en el sótano de las oficinas centrales —a dos edificios de la máquina—. El día que se escribió, el manual era perfecto. Pero la máquina, con los años, cambió: un técnico le añadió una válvula de seguridad nueva, otro cambió la secuencia de encendido, un tercero recalibró la presión máxima. Cada uno de esos cambios debería haber ido al manual, pero actualizar el manual significaba ir a otro edificio, bajar al sótano, encontrar la página, reescribirla —y nadie lo hizo, porque siempre había algo más urgente—. Hoy el manual del sótano describe una máquina que ya no existe: dice que la presión máxima es un valor que dejó de ser cierto hace tres años. Un operador nuevo que confíe en él puede lastimarse. El manual es completo, encuadernado y peligroso, porque está desincronizado de la máquina real.
La etiqueta pegada en la máquina. La misma fábrica, para lo crítico, hace otra cosa: pega etiquetas en la máquina misma. Junto a la palanca de encendido, una etiqueta con la secuencia; junto a la válvula, una etiqueta con la presión máxima; en el panel, una etiqueta con la advertencia. Y hay una regla de oro: cuando un técnico modifica la máquina, actualiza la etiqueta en el mismo trabajo —no puede cerrar la orden de mantenimiento sin repintar la etiqueta afectada—. Cuando alguien cambia la presión máxima, la etiqueta que está a diez centímetros de la válvula se actualiza en el acto, porque está ahí, a la vista, imposible de ignorar. El resultado: las etiquetas de la máquina siempre dicen la verdad, porque viven sobre la cosa que describen y se actualizan como parte de cambiarla. No hay un "después" en otro edificio; el cambio y la etiqueta ocurren en el mismo lugar, al mismo tiempo.
Aquí está el punto, y es el corazón de living documentation: la doc que sobrevive no es la más completa ni la mejor escrita; es la que vive tan pegada a la cosa que describe que actualizarla es parte de cambiar la cosa. El manual del sótano era más completo que las etiquetas —y sin embargo era inútil y peligroso, porque la distancia lo desincronizó—. Las etiquetas eran breves —y sin embargo eran las únicas confiables, porque la proximidad las mantuvo vivas—. La wiki desconectada del código es el manual del sótano: completa el día uno, podrida al año, peligrosa cuando alguien confía en ella. La documentación viva es la etiqueta en la máquina: vive en el repo, junto al código, y se actualiza en el mismo cambio. Esta lección mide por qué la etiqueta gana, y por qué la wiki no se degrada despacio sino que cae por un acantilado de confianza.
Ejemplo trabajado: la wiki que se pudre contra la doc que vive
Vamos a medir lo que la analogía afirma. Tomamos un sistema con 12 hechos documentados —12 cosas que la doc afirma sobre el sistema—. El sistema evoluciona: en cada release, una fracción de los hechos cambia (lo llamamos drift, aquí 20% por release). La diferencia entre las dos docs está en una sola variable: la probabilidad de que un hecho se re-sincronice cuando cambia.
- La wiki vive lejos del código, así que actualizarla es un acto aparte que casi nunca ocurre: probabilidad de sincronizar, 10%.
- La doc viva vive pegada al código y se actualiza en el mismo PR que cambia el sistema: probabilidad de sincronizar, 97%.
Y añadimos el fenómeno clave: un piso de confianza. Cuando la exactitud de una doc cae bajo 70%, los devs dejan de confiar en toda ella —porque no pueden saber qué 70% sigue bien—, así que su valor efectivo cae a cero. Medimos la exactitud de las dos docs release tras release, y si en cada punto se confía en ellas:
# Living documentation: la doc que vive PEGADA al codigo se actualiza en el mismo
# cambio y se mantiene fresca; la wiki lejos del codigo se actualiza casi nunca y
# se pudre. Modelamos 12 hechos documentados. En cada release, una fraccion de los
# hechos cambia (drift). La doc "viva" (junto al codigo) se re-sincroniza casi
# siempre; la wiki casi nunca. Y hay un abismo: cuando la exactitud baja de cierto
# umbral, los devs dejan de confiar en TODA la doc (no saben que parte sigue bien),
# asi que su valor efectivo se desploma a cero aunque parte siga correcta.
DRIFT = 0.20 # 20% de los hechos son tocados por release
SYNC_LIVING = 0.97 # la doc junto al codigo se actualiza en el mismo PR
SYNC_WIKI = 0.10 # la wiki lejos del codigo casi nunca se actualiza
TRUST_FLOOR = 0.70 # bajo esta exactitud se pierde la confianza en TODA la doc
def accuracy(sync, k):
# Fraccion de los hechos que sigue siendo correcta tras k releases.
decay = DRIFT * (1 - sync)
return (1 - decay) ** k
def effective_value(sync, k):
# Una doc en la que no se confia vale 0, aunque parte siga siendo correcta.
a = accuracy(sync, k)
return a if a >= TRUST_FLOOR else 0.0
print(f"{'release':>8}{'wiki %':>9}{'confia?':>9}{'viva %':>9}{'confia?':>9}")
print("-" * 44)
for k in range(0, 9):
aw, al = accuracy(SYNC_WIKI, k), accuracy(SYNC_LIVING, k)
tw = "si" if aw >= TRUST_FLOOR else "NO"
tl = "si" if al >= TRUST_FLOOR else "NO"
print(f"{k:>8}{aw * 100:>8.1f}%{tw:>9}{al * 100:>8.1f}%{tl:>9}")
print("-" * 44)
k = 8
print(f"Al release {k}: la wiki es {accuracy(SYNC_WIKI, k) * 100:.0f}% exacta,")
print(f"pero VALE {effective_value(SYNC_WIKI, k) * 100:.0f}% (nadie confia en ella).")
print(f"La doc viva es {accuracy(SYNC_LIVING, k) * 100:.0f}% exacta y VALE "
f"{effective_value(SYNC_LIVING, k) * 100:.0f}%.")
print("La wiki cruzo el piso de confianza en el release 2 y no volvio.")Qué esperar. Al correr el archivo, la salida es exactamente esta:
release wiki % confia? viva % confia?
--------------------------------------------
0 100.0% si 100.0% si
1 82.0% si 99.4% si
2 67.2% NO 98.8% si
3 55.1% NO 98.2% si
4 45.2% NO 97.6% si
5 37.1% NO 97.0% si
6 30.4% NO 96.5% si
7 24.9% NO 95.9% si
8 20.4% NO 95.3% si
--------------------------------------------
Al release 8: la wiki es 20% exacta,
pero VALE 0% (nadie confia en ella).
La doc viva es 95% exacta y VALE 95%.
La wiki cruzo el piso de confianza en el release 2 y no volvio.
Lee la tabla despacio, columna por columna, porque tiene dos lecciones encimadas.
La primera lección: la wiki se pudre y la doc viva no. Fíjate en la columna wiki %. Empieza en 100% —recién escrita, todo cierto—, pero se desploma: al release 1 ya perdió casi una quinta parte (82%), al release 4 está por debajo de la mitad (45%), y al release 8 solo el 20% de lo que dice sigue siendo cierto. Ochenta por ciento de la wiki miente. ¿Por qué? Porque cada release cambia el 20% de los hechos, y la wiki solo re-sincroniza el 10% de lo que cambia —el resto se queda escrito describiendo un sistema que ya no existe—. Ahora mira viva %: apenas se mueve. Empieza en 100% y al release 8 sigue en 95%. La misma cantidad de cambio golpea a las dos docs; la diferencia es que la doc viva re-sincroniza el 97% de lo que cambia, porque actualizarla es parte del mismo PR que hace el cambio. La wiki y la doc viva reciben idéntico drift; lo que las separa es la proximidad al código, y esa sola variable es la diferencia entre 20% y 95% de exactitud.
La segunda lección, la que hace todo peor: el abismo de la confianza. Mira las columnas confia?. La doc viva dice "si" en todos los releases —siempre está por encima del piso de 70%—. La wiki dice "si" solo en los releases 0 y 1; en el release 2, con 67.2% de exactitud, cruza el piso y dice "NO", y ya no vuelve. Y aquí está el golpe: en el release 8, la wiki todavía es 20% exacta —una quinta parte de lo que dice sigue siendo cierto—, pero su valor efectivo es 0%. ¿Cómo puede valer cero algo que es 20% correcto? Porque nadie sabe cuál 20%. Cuando abres una doc de la que sabes que la mayoría está mal, no puedes usar ninguna parte con confianza: cada afirmación podría ser de la quinta parte cierta o de las cuatro quintas falsas, y no tienes forma de distinguir sin verificar contra el código —y si vas a verificar todo contra el código, la doc no te ahorró nada—. Una doc parcialmente podrida no vale su fracción correcta; vale cero, porque la incertidumbre envenena todo el documento.
Ese es el abismo, y es la razón por la que la doc no se degrada suave sino por un acantilado. Mientras la exactitud está alta, el pequeño porcentaje de error se tolera (verificas un caso raro y ya). Pero hay un umbral —aquí 70%— bajo el cual la doc deja de ser "casi correcta con algún error" y pasa a ser "no confiable", y en ese momento pierde todo su valor de golpe, no proporcionalmente. La wiki cruzó ese umbral en el release 2 —apenas medio año, quizás— y desde entonces es un documento muerto que ocupa espacio: la gente lo abre, ve que no le puede creer, lo cierra, y va a preguntarle a la persona que sabe. La doc existe, pero el bus factor no bajó ni un punto.
Como barras, el contraste al release 8 se ve así:
Exactitud y valor efectivo al release 8
wiki exactitud |#### 20% valor | 0%
doc viva exactitud |################### 95% valor |################### 95%
─────────────────────────────
La wiki es 20% cierta pero vale 0: nadie sabe cual 20%. El acantilado de confianza.
Profundización: qué mantiene viva la doc, y qué la mata
El experimento aisló la variable que decide todo: la probabilidad de re-sincronizar un hecho cuando cambia. Vale la pena entender qué determina esa probabilidad en el mundo real, porque ahí está la receta de la doc que sobrevive.
Lo que hace que la probabilidad de sincronizar sea alta es una sola cosa: la distancia entre la doc y el código. No distancia física, sino distancia en el flujo de trabajo. Si actualizar la doc está en el camino de hacer el cambio —si el mismo PR que cambia payments incluye el archivo de doc de payments, y el revisor lo ve—, la doc se actualiza casi siempre, porque no actualizarla sería un hueco visible en el trabajo. Si actualizar la doc está fuera del camino —si vive en otra herramienta, requiere acordarse, abrir Confluence, encontrar la página— entonces se actualiza casi nunca, porque "después" no llega: siempre hay algo más urgente, y nadie audita si la wiki quedó al día. La proximidad no es estética; es lo que determina si actualizar la doc es un acto que ocurre por defecto o un acto que requiere disciplina heroica sostenida durante años (que nunca se sostiene).
De ahí sale la idea más profunda de living documentation, la que Cyrille Martraire empuja hasta el extremo: la mejor documentación es la que no se mantiene aparte, porque se deriva de la fuente de verdad. Piénsalo en grados de proximidad. El grado más pobre es la wiki: doc totalmente separada, sincronización manual, se pudre. Un grado mejor es la doc en el repo, junto al código, revisada en el mismo PR (docs-as-code, la lección 3): sincronización forzada por el flujo, sobrevive. El grado óptimo, cuando es posible, es la doc generada desde el código o los tests: un diagrama que se dibuja a partir de la estructura real del código, una lista de endpoints que sale del propio router, ejemplos de uso que son los tests que corren en CI. Esa doc no se puede desincronizar, porque no existe aparte: es una proyección de la fuente de verdad. Cuando el código cambia, la doc generada cambia con él, sin que nadie tenga que acordarse. No siempre se puede generar todo —el porqué de una decisión no se deriva del código, hay que escribirlo—, pero la regla es clara: cuanto más cerca de la fuente de verdad vive la doc, más sobrevive, y la wiki desconectada es el punto más lejano posible.
Ahora, el matiz honesto, para no caer en un absolutismo tonto. "Living documentation" no significa "genera todo automáticamente y no escribas nada". Hay conocimiento que no se deriva del código y que hay que escribir a mano: sobre todo el porqué —por qué payments está separado, por qué se eligió una cola en vez de escritura directa—. El código muestra qué hace el sistema, nunca por qué se decidió así; ese porqué es justo lo que un ADR captura y lo que más sobrevive (lo veremos en las lecciones 4 y 5). La lección de living documentation no es "no escribas doc"; es "escribe la doc que hay que escribir lo más cerca posible del código y actualízala en el mismo cambio, y genera desde el código todo lo que se pueda generar, para que la parte que mantienes a mano sea la mínima —la estable, la del porqué—". La doc que sobrevive es una combinación: lo generado (que no se puede pudrir) más lo escrito-cerca-del-código (que se mantiene vivo por proximidad).
Hay una consecuencia cultural que conviene nombrar. En un equipo con living documentation, "documentar" deja de ser una fase aparte —esa reunión de "vamos a documentar el sistema" que se pospone para siempre— y se vuelve parte de "cambiar el sistema": el PR no está completo hasta que su doc está al día, igual que no está completo hasta que sus tests pasan. Eso suena a más trabajo, pero es menos: mantener una etiqueta al día cuando estás con las manos en la máquina cuesta minutos; reconstruir un manual podrido del sótano cuesta semanas —y para cuando lo reconstruyes, ya se volvió a pudrir—. La doc viva es barata porque se hace en el momento; la wiki es cara porque pretende hacerse después, y "después" o no llega o llega tan tarde que hay que rehacer todo.
Errores comunes
La wiki desconectada del código (el manual del sótano). Qué pasa: el equipo documenta en una herramienta separada del código —Confluence, Notion, una carpeta de Docs— porque es cómodo escribir ahí. El código sigue cambiando, la wiki se queda quieta, y en meses la wiki describe un sistema que ya no existe. Por qué pasa: escribir lejos del código no requiere tocar el repo ni pasar por review, así que en el momento es el camino de menor resistencia; el costo (la desincronización) aparece después y es de otro. Cómo detectarlo: si tu doc vive fuera del repo, si actualizarla es un acto separado de cambiar el código, o si la respuesta a "¿esto está al día?" es "seguramente no", tu wiki es el manual del sótano. Cómo corregirlo: acercar la doc al código —al repo, revisada en el mismo PR (lección 3)— y generar desde el código todo lo que se pueda. La proximidad es lo único que la mantiene viva; la disciplina de "acordarse de actualizar la wiki" no se sostiene durante años.
Creer que una doc parcialmente correcta vale su fracción. Qué pasa: el equipo tolera una doc que "está como 60% al día" pensando que 60% de valor es mejor que nada, y la deja pudrirse un poco más cada release. Pero cruza el piso de confianza y, de golpe, deja de usarse por completo: nadie puede saber qué 60% es el bueno. Por qué pasa: se piensa en la exactitud de la doc como una escala continua (más exacta, más útil), cuando en realidad hay un abismo —bajo cierto umbral, el valor no baja proporcionalmente, cae a cero—. Cómo detectarlo: si tu doc tiene errores conocidos que "ya casi nadie mira", o si la gente prefiere preguntar a leer la doc, ya cruzaste el abismo aunque parte siga bien. Cómo corregirlo: tratar la exactitud de la doc como un umbral, no una escala —mantenerla muy alta (con proximidad y generación) o asumir que no vale nada—; una doc al 95% se usa, una al 60% no se usa aunque tenga más verdad absoluta que su reputación.
Documentar todo a mano "para que esté completo". Qué pasa: el equipo intenta mantener a mano una doc exhaustiva —cada endpoint, cada diagrama, cada detalle— y como es imposible mantener tanto sincronizado, todo se pudre por igual, incluido lo estable que sí valía. Por qué pasa: se confunde "documentación viva" con "documentación completa", y la completitud a mano es justo lo que garantiza la putrefacción, porque hay demasiado que mantener. Cómo detectarlo: si tu equipo tiene una doc enorme y desactualizada, o si "mantener la doc" se siente como una carga infinita, estás manteniendo a mano lo que debería generarse o no documentarse. Cómo corregirlo: generar desde el código todo lo que se pueda (no se pudre), mantener a mano solo lo estable y el porqué (lo mínimo, lección 5), y aceptar que lo volátil se lee del código, no de la doc. La doc viva es pequeña y cierta, no grande y podrida.
Ejercicios
Ejercicio 1 — Por qué 20% vale 0. En el ejemplo, al release 8 la wiki es 20% exacta pero su valor efectivo es 0%. Un ingeniero protesta: "20% de exactitud no es cero; una de cada cinco cosas que dice es cierta, eso tiene algún valor". Explica por qué, en la práctica, ese 20% vale cero, y qué tendría que ser verdad para que una doc parcialmente correcta sí valiera su fracción.
Ver solución
El 20% vale cero en la práctica porque nadie sabe cuál 20%. Cuando abres la wiki y lees una afirmación —"payments cobra por escritura directa al proveedor X"—, no tienes forma de saber si esa afirmación es de la quinta parte que sigue siendo cierta o de las cuatro quintas que ya son falsas. Para usarla con confianza tendrías que verificarla contra el código; y si vas a verificar cada afirmación contra el código, la doc no te ahorró nada —te habría salido igual leer el código directo—. Peor aún: hay un costo negativo, porque una afirmación falsa que parece autoritativa (está escrita en la doc oficial) puede mandarte por el camino equivocado antes de que verifiques. Así que una doc en la que la mayoría está mal no vale su fracción correcta: vale cero o menos, porque la incertidumbre sobre cuál parte es correcta envenena todo el documento.
Para que una doc parcialmente correcta sí valiera su fracción, tendría que ser verdad que puedes saber qué parte es correcta sin verificarla contra el código. Por ejemplo, si la doc marcara cada afirmación con su fecha de última verificación y su estado (verificada en CI / escrita a mano / posiblemente obsoleta), podrías confiar en la parte verificada e ignorar el resto. Eso es justo lo que logra la doc generada desde el código o los tests: cada afirmación generada es cierta por construcción, así que su valor no se contamina con las partes escritas a mano. La lección: el valor de una doc no depende solo de qué fracción es correcta, sino de si puedes distinguir la parte correcta —y una wiki podrida no te deja distinguir, por eso vale cero—.
Ejercicio 2 — Misma drift, distinto destino. En el modelo, la wiki y la doc viva reciben exactamente el mismo drift (20% de los hechos cambian por release) y sin embargo terminan en 20% y 95% de exactitud. Explica, sin código, cuál es la única variable que produce esa diferencia enorme, qué representa en el mundo real, y por qué no se puede compensar con "más disciplina" para actualizar la wiki.
Ver solución
La única variable que difiere es la probabilidad de re-sincronizar un hecho cuando cambia: 97% para la doc viva, 10% para la wiki. El mismo drift golpea a las dos, pero la doc viva vuelve a poner al día casi todo lo que cambió, mientras la wiki deja sin actualizar el 90% de lo que cambió —y ese residuo sin actualizar es lo que se acumula release tras release hasta pudrir el documento—. En el mundo real, esa probabilidad representa la distancia entre la doc y el código en el flujo de trabajo: la doc viva se actualiza en el mismo PR que hace el cambio (actualizarla está en el camino, es casi automático), la wiki se actualiza en un acto aparte, en otra herramienta, que requiere acordarse (actualizarla está fuera del camino, casi nunca ocurre).
No se puede compensar con "más disciplina" porque la disciplina de actualizar una wiki desconectada requiere que cada persona, en cada cambio, durante años, se acuerde de hacer un trabajo aparte que nadie audita y que no bloquea nada. Eso no se sostiene: basta con que la sincronización falle un poco en cada release —que es lo normal cuando depende de la memoria y la buena voluntad— para que el residuo se acumule y la doc se pudra. La solución no es pedir más heroísmo sostenido (que siempre falla), sino cambiar la estructura para que actualizar la doc esté en el camino del cambio y no fuera de él: acercar la doc al código, revisarla en el mismo PR, generarla desde la fuente. Cuando actualizar la doc es parte de cambiar el código, la alta probabilidad de sincronización sale gratis; cuando es un acto aparte, ninguna cantidad de disciplina la sostiene.
Ejercicio 3 — Qué generar y qué escribir. Living documentation empuja a generar desde el código todo lo que se pueda, y escribir a mano solo lo mínimo. Para el módulo de payments de Mercado, clasifica estas cuatro piezas de doc en "se puede generar desde el código" o "hay que escribirla a mano", y explica por qué: (a) la lista de endpoints que expone payments; (b) por qué payments está separado del núcleo y cobra por cola en vez de escritura directa; (c) el diagrama de qué otros módulos llaman a payments; (d) las reglas de negocio de qué transacciones se pueden reembolsar.
Ver solución
(a) Lista de endpoints → se puede generar. Los endpoints que expone payments están definidos en el propio código (el router, las rutas). Una lista de endpoints escrita a mano se pudre en el primer cambio; una generada desde el router (por ejemplo, un OpenAPI que sale del código) es cierta por construcción y se actualiza sola cuando se añade o quita un endpoint. Se genera, no se escribe.
(b) Por qué payments está separado y cobra por cola → hay que escribirla a mano. Esto es el porqué de una decisión, y el porqué no está en el código: el código muestra que hay una cola, nunca por qué se eligió la cola en vez de escritura directa (aislar el tráfico externo del núcleo, aceptar un retraso a cambio de seguridad). Ese razonamiento hay que escribirlo —es justo lo que captura un ADR—, y es lo más estable y lo que más sobrevive. Se escribe a mano, cerca del código, y casi no cambia.
(c) Diagrama de quién llama a payments → se puede generar (en buena medida). Las dependencias entre módulos —quién importa o llama a payments— están en el código y se pueden extraer con herramientas de análisis de dependencias, produciendo un diagrama que se actualiza con el código. Un diagrama de dependencias dibujado a mano se desincroniza; uno generado desde la estructura real no. (El C4 de más alto nivel, con la intención y las fronteras, sí lleva mano; el detalle de dependencias se genera.)
(d) Reglas de negocio de reembolsos → caso mixto, tiende a escribirse. Las reglas implementadas están en el código (y idealmente en los tests, que pueden servir como doc viva ejecutable de "qué se reembolsa y qué no"). Pero la intención de negocio —por qué la regla es así, qué caso de negocio la motivó— se escribe a mano. Lo ideal de living documentation aquí es que los tests de las reglas de reembolso sean la doc de qué hace el sistema (no se pueden pudrir, porque si el código cambia y el test no, el test falla), y que a mano se documente solo el porqué de negocio. Se combinan: el qué se deriva de los tests, el porqué se escribe.
El patrón general: el qué (endpoints, dependencias, reglas implementadas) se genera desde el código o los tests, porque ahí vive la verdad y no se puede pudrir; el por qué (decisiones, intención, límites) se escribe a mano, cerca del código, porque no está en ninguna otra parte y es lo más estable. Esa combinación —generar el qué, escribir el porqué— es la documentación que sobrevive.
Resumen y siguiente paso
En esta lección entendiste por qué la mayoría de la documentación no sobrevive: se pudre porque vive lejos del código y actualizarla es un acto aparte que casi nunca ocurre. Viste, con la etiqueta en la máquina contra el manual en el sótano, que la doc que sobrevive no es la más completa sino la que vive tan pegada a la cosa que actualizarla es parte de cambiarla —living documentation—. Y lo mediste dos veces: primero, que la misma drift produce 20% de exactitud en la wiki contra 95% en la doc viva, y que la única variable que lo explica es la proximidad al código; segundo, el abismo de la confianza —cuando la exactitud cae bajo 70%, la doc entera vale cero aunque parte siga correcta, porque nadie sabe qué parte, y la wiki cruza ese piso ya en el release 2—. Aprendiste la receta: generar desde el código todo lo que se pueda (no se pudre), escribir a mano solo lo estable y el porqué (lo mínimo), y mantenerlo todo cerca del código.
Antes de avanzar deberías poder: explicar por qué una doc 20% correcta vale cero (el abismo de confianza); nombrar la única variable que separa a la wiki de la doc viva (la proximidad al código, no la disciplina); y clasificar qué se genera y qué se escribe a mano.
La lección 3 toma el principio de esta lección —la proximidad mantiene viva la doc— y lo convierte en una práctica concreta: docs-as-code. Vas a ver cómo poner la doc en el repo, en Markdown y PlantUML, revisada en los mismos PRs que el código, y —lo más potente— validada en CI: un test que revisa que la doc no se haya desincronizado del código y rompe el build si un ADR referencia un módulo que ya no existe. Con eso, "la doc se pudrió" deja de ser un problema invisible que se descubre meses después y se convierte en un test rojo que salta en el acto. La proximidad de esta lección, hecha mecánica.
Recursos
- Cyrille Martraire, Living Documentation: Continuous Knowledge Sharing by Design (Addison-Wesley, 2019), parte I — la fuente del concepto de esta lección: la doc que sobrevive es la que vive pegada al código y, cuando es posible, se deriva de la fuente de verdad en vez de mantenerse aparte. En inglés.
- Write the Docs — "Docs as Code" — la comunidad que impulsa tratar la doc como código: en el repo, en texto plano, cerca de lo que describe. Buen puente hacia la lección 3. En inglés.
- Martin Fowler — "Living Documentation" y el hub de arquitectura — sobre por qué la doc útil es la que se mantiene viva por proximidad, no la que se escribe una vez. En inglés.
- Andrew Hunt y David Thomas, The Pragmatic Programmer, 20th Anniversary Edition (Addison-Wesley, 2019), tema "It's All Writing" y el principio DRY aplicado a la doc — por qué duplicar conocimiento entre el código y una doc separada garantiza que se desincronicen. En inglés.