Documentar lo estable, no lo volátil

Descripción

La lección anterior armó el sistema de documentación —C4, ADR, arc42— y terminó con una advertencia: el sistema solo sobrevive si lo llenas con la información correcta. Esta lección es sobre cuál es la información correcta, y su respuesta es la regla más importante y más ignorada de toda la documentación: documenta lo estable, no lo volátil. Lo estable es lo que cambia poco —los límites entre módulos, las decisiones de arquitectura, el porqué de las cosas—; lo volátil es lo que cambia todo el tiempo —la lista exacta de endpoints, las firmas de las funciones, los valores de configuración, el estado de las tareas—. La intuición de mucha gente es documentar lo volátil, porque es lo más concreto y visible ("aquí está la lista de todos nuestros endpoints"). Y es exactamente el error: lo volátil queda obsoleto antes de que alguien lo lea, mientras que lo estable —lo que de verdad ayuda— queda sin documentar porque no alcanzó el tiempo.

La razón profunda es económica, y esta lección la mide. Cada pieza de documentación rinde (alguien la lee y le ahorra tiempo) pero cuesta mantenerla sincronizada cada vez que lo documentado cambia. El ROI de documentar algo es beneficio menos costo de mantenimiento. Y aquí está el giro que casi nadie ve: la variable que decide el ROI no es la importancia de la información, sino su volatilidad (su churn). Algo muy importante pero muy volátil —la lista de endpoints es importante— tiene ROI negativo, porque mantenerlo sincronizado cuesta más de lo que rinde: cambia tan seguido que o pagas una fortuna en actualizaciones o la doc se pudre y vale cero (el abismo de la lección 2). Algo estable, aunque parezca menos "concreto" —por qué payments está separado—, tiene ROI alto, porque casi no cuesta mantenerlo y se lee durante años. Esta lección ejecuta ese ROI sobre seis piezas típicas de doc y muestra que el churn es lo que voltea el signo.

Conexión con el módulo. Es la lección que dice qué poner dentro del sistema de la lección 4. Las lecciones 2 y 3 dijeron que la doc debe vivir cerca del código y mantenerse sincronizada; esta explica por qué, aun con esa disciplina, no debes documentar todo a mano —lo volátil hay que generarlo desde el código o dejárselo al código, porque documentarlo a mano tiene ROI negativo—. Cierra el círculo con living documentation (lección 2): "genera lo volátil, escribe lo estable" es la misma frontera vista desde el ROI. Con la analogía del módulo: es la capa del manual que dice dónde está la llave de paso (estable, útil por años) y no de qué color está pintada la sala hoy (volátil, obsoleto en un mes). Frontera con el resto: no re-enseñamos la mecánica del ADR ni del C4; usamos que el ADR captura lo estable (el porqué) y por eso es lo que más vale la pena mantener.

Una analogía: el manual de la casa contra el post-it en el refri

Piensa en dos tipos de información que hay en cualquier casa, y en qué pasa cuando intentas documentar cada uno.

La llave de paso del agua: información estable. Dónde está la llave de paso general del agua no cambia en años —quizás nunca, en toda la vida de la casa—. Por eso vale la pena documentarlo bien: escribirlo en el manual de la casa, con precisión ("jardín, detrás del rosal, tapa verde"). Ese dato, escrito una vez, sirve al dueño de hoy, al de dentro de cinco años, al plomero que venga en una emergencia. El esfuerzo de documentarlo se paga muchísimas veces, porque lo escribiste una vez y sigue siendo cierto durante toda la vida de la casa. Documentar lo estable es una inversión que rinde por años con un solo pago.

El menú de la semana: información volátil. Ahora imagina que decides "documentar" también el menú de comidas de la casa, pegándolo en un post-it en el refrigerador: "lunes pasta, martes pescado...". El menú cambia cada semana. Así que para que el post-it siga siendo cierto, tienes que reescribirlo cada semana —y si un día no lo reescribes, el post-it miente: dice "martes pescado" cuando ya cambiaste a pollo—. Documentar el menú es un pozo sin fondo: cuesta trabajo constante mantenerlo al día, y el valor de tenerlo escrito es bajo (de todas formas abres el refri y ves qué hay). El esfuerzo de documentarlo nunca se termina de pagar, porque cada semana hay que volver a pagarlo, y si dejas de pagar, se vuelve mentira. Documentar lo volátil es un gasto recurrente que rinde poco.

Aquí está la regla: documenta la llave de paso, no el menú. No porque el menú sea menos importante (comer importa), sino porque el menú es volátil —cambia tan seguido que documentarlo a mano cuesta más de lo que rinde y siempre está a punto de mentir—. Para lo volátil, la solución no es un post-it que reescribes cada semana; es mirar el refri (ir a la fuente: abres y ves qué hay). En software, "mirar el refri" es leer el código: la lista exacta de endpoints, las firmas de las funciones, los valores de configuración viven en el código, que es la fuente de verdad y siempre está al día; documentarlos aparte a mano es reescribir el post-it del menú cada semana. Lo que sí va al manual —escrito una vez, útil por años— es lo estable: la llave de paso (los límites), por qué la cisterna se movió (las decisiones). Esta lección mide, con el ROI, por qué la llave de paso vale documentarla y el menú no.

Ejemplo trabajado: el ROI de documentar, y el churn que lo voltea

Vamos a medir el ROI de documentar seis piezas típicas de la doc de Mercado. Cada pieza tiene cuatro números: cuánto cambia al año (su churn), cuántas veces la leen al año, cuánto valor da cada lectura (horas ahorradas), y cuánto cuesta cada actualización para mantenerla sincronizada. El beneficio es lecturas por valor; el costo de mantenimiento es churn por costo de actualización; el ROI es la diferencia. La pregunta que responde el experimento: ¿qué variable decide si el ROI es positivo o negativo?

# Documentar lo ESTABLE, no lo VOLATIL. Cada pieza de doc rinde (la leen y ahorra
# tiempo) pero cuesta mantenerla sincronizada cada vez que lo documentado cambia.
# El ROI = beneficio - costo de mantenimiento. Lo estable (limites, decisiones)
# cambia poco: barato de mantener, alto ROI. Lo volatil (lista de endpoints, firmas
# de funciones, estado de tareas) cambia todo el tiempo: mantenerlo cuesta mas de lo
# que rinde -> ROI negativo. Eso NO se documenta a mano: se genera o se deja al codigo.
ITEMS = [
    # (pieza, churn=cambios/ano, reads/ano, valor_por_lectura_h, costo_por_update_h)
    ("module_boundaries (C4)",    2,  60, 0.50, 1.00),
    ("key_decisions (ADR)",       1,  40, 0.75, 1.00),
    ("how_to_run (README)",       4,  50, 0.40, 0.50),
    ("api_endpoint_list",        40,  30, 0.20, 0.50),
    ("function_signatures",     200,  20, 0.10, 0.25),
    ("current_task_status",     120,  10, 0.10, 0.30),
]

print(f"{'pieza':<26}{'churn':>7}{'beneficio':>11}{'costo':>8}{'ROI':>8}")
print("-" * 60)
rows = []
for name, churn, reads, value, cost_up in ITEMS:
    benefit = reads * value
    maint = churn * cost_up
    roi = benefit - maint
    rows.append((name, churn, benefit, maint, roi))
    print(f"{name:<26}{churn:>7}{benefit:>10.0f}h{maint:>7.0f}h{roi:>+7.0f}h")
print("-" * 60)
print("\nDecision (ordenada por ROI):")
for name, churn, benefit, maint, roi in sorted(rows, key=lambda r: -r[4]):
    verb = "DOCUMENTA a mano (estable)" if roi > 0 else "NO a mano (volatil)"
    print(f"  {roi:>+6.0f}h  {name:<26} -> {verb}")
print("\nLa variable que voltea el ROI es el CHURN (la volatilidad), no la importancia.")

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

pieza                       churn  beneficio   costo     ROI
------------------------------------------------------------
module_boundaries (C4)          2        30h      2h    +28h
key_decisions (ADR)             1        30h      1h    +29h
how_to_run (README)             4        20h      2h    +18h
api_endpoint_list              40         6h     20h    -14h
function_signatures           200         2h     50h    -48h
current_task_status           120         1h     36h    -35h
------------------------------------------------------------

Decision (ordenada por ROI):
     +29h  key_decisions (ADR)        -> DOCUMENTA a mano (estable)
     +28h  module_boundaries (C4)     -> DOCUMENTA a mano (estable)
     +18h  how_to_run (README)        -> DOCUMENTA a mano (estable)
     -14h  api_endpoint_list          -> NO a mano (volatil)
     -35h  current_task_status        -> NO a mano (volatil)
     -48h  function_signatures        -> NO a mano (volatil)

La variable que voltea el ROI es el CHURN (la volatilidad), no la importancia.

Lee la tabla mirando dos columnas juntas: churn y ROI. La historia entera está en su relación.

Las tres piezas de ROI positivo son las estables. key_decisions (ADR) tiene churn 1 —las decisiones de arquitectura casi no cambian— y ROI +29h: la escribes una vez, casi no la mantienes, y la leen 40 veces al año durante años. module_boundaries (C4) tiene churn 2 y ROI +28h: los límites entre módulos cambian poco, así que documentarlos rinde. how_to_run (README) tiene churn 4 y ROI +18h: cómo correr el proyecto cambia de vez en cuando, pero poco, y lo lee cada dev nuevo. Estas tres son la llave de paso del agua: información estable que, documentada una vez, rinde por años con poco mantenimiento.

Las tres de ROI negativo son las volátiles. api_endpoint_list tiene churn 40 —los endpoints cambian seguido— y ROI −14h: aunque la lista de endpoints es útil (beneficio 6h), mantenerla sincronizada a mano cuesta 20h al año, más de lo que rinde. function_signatures tiene churn 200 y ROI −48h: las firmas de funciones cambian constantemente, y documentarlas a mano es un pozo sin fondo. current_task_status tiene churn 120 y ROI −35h: el estado de las tareas cambia a diario, documentarlo a mano no tiene sentido. Estas tres son el menú del refri: reescribir el post-it cada semana cuesta más que el valor de tenerlo escrito.

Y el corazón, en la última línea: la variable que voltea el ROI es el CHURN, no la importancia. Fíjate en algo contraintuitivo. api_endpoint_list tiene beneficio 6h y key_decisions tiene 30h —las decisiones rinden cinco veces más—, pero esa no es la razón por la que una tiene ROI positivo y la otra negativo. La razón es el costo de mantenimiento, que depende del churn: key_decisions cuesta 1h al año de mantenimiento (churn 1), api_endpoint_list cuesta 20h (churn 40). Aunque los endpoints fueran más importantes que las decisiones, seguirían teniendo ROI negativo, porque su volatilidad hace que mantenerlos sincronizados cueste más de lo que rinde. La pregunta correcta antes de documentar algo no es "¿es importante?" sino "¿cambia poco?". Lo importante-y-volátil no se documenta a mano; lo importante-y-estable, sí.

Entonces, ¿qué haces con lo importante-y-volátil, como la lista de endpoints, que sí sirve? No lo documentas a mano —lo generas desde el código—. La lista de endpoints sale del router (un OpenAPI generado); las firmas viven en el código y se leen ahí o se generan; el estado de las tareas vive en el tracker, no en la doc de arquitectura. Generar desde la fuente tiene costo de mantenimiento cero (se actualiza sola cuando el código cambia), así que convierte el ROI negativo de documentar-a-mano en un ROI positivo de generar. Es la conexión exacta con living documentation (lección 2): el churn alto no significa "no documentes esta información", significa "no la documentes a mano: genérala desde el código, donde no se puede pudrir".

Como gráfico, el ROI contra el churn se ve así:

ROI (horas/ano) segun el churn de lo documentado
  key_decisions (churn 1)    +29h  ###############  ESTABLE -> documenta a mano
  module_boundaries (churn 2)+28h  ##############   ESTABLE -> documenta a mano
  how_to_run (churn 4)       +18h  #########        ESTABLE -> documenta a mano
  ─────────────────────────────── 0 ───────────────────────────────
  api_endpoint_list (churn 40)-14h ######           VOLATIL -> genera desde el codigo
  current_task_status(churn120)-35h ##########      VOLATIL -> vive en el tracker
  function_signatures(churn200)-48h #############    VOLATIL -> vive en el codigo
      A mas churn, mas negativo el ROI. El churn voltea el signo.

Profundización: por qué el churn manda, y cómo trazar la línea

El experimento reveló que el churn —no la importancia— decide si documentar algo a mano vale la pena. Vale la pena entender por qué es así y cómo usar esa regla en la práctica.

La mecánica es simple pero contraintuitiva. El beneficio de una doc depende de cuánto y cuán valiosamente se lee; el costo depende de cuánto cambia lo documentado, porque cada cambio obliga a una actualización (o, si no la haces, a que la doc se pudra). Como el costo crece con el churn y el beneficio no, hay un punto de churn a partir del cual el costo supera al beneficio y el ROI se vuelve negativo. Y aquí está lo contraintuitivo: la importancia de la información sube el beneficio, pero no baja el costo. Una lista de endpoints muy importante se lee más (más beneficio), pero sigue cambiando 40 veces al año (mismo costo alto). Por eso la importancia no salva a lo volátil: puedes tener información importantísima cuyo ROI a mano es negativo, simplemente porque cambia demasiado. La volatilidad es una propiedad del costo, y el costo es lo que hunde el ROI.

De ahí sale la frontera práctica, que es la misma que vimos en living documentation pero ahora justificada por el ROI: lo estable se escribe a mano; lo volátil se genera desde el código o se deja en su fuente. Lo estable —decisiones (ADR), límites (C4), cómo correrlo (README), riesgos conocidos— cambia poco, así que su costo de mantenimiento es bajo y su ROI a mano es positivo; además, buena parte de lo estable (sobre todo el porqué) no se puede generar desde el código, porque no está ahí, así que escribirlo a mano es la única opción y por suerte es barata. Lo volátil —endpoints, firmas, configuración, estado— cambia mucho, así que su costo de mantenimiento a mano es prohibitivo; pero por suerte sí se puede leer o generar desde su fuente (el código, el router, el tracker), donde está siempre al día. La naturaleza ayuda: lo que hay que escribir a mano (el porqué estable) es justo lo barato de mantener, y lo caro de mantener (el qué volátil) es justo lo que se puede generar. La regla se acomoda sola.

Hay un patrón que aclara mucho: el software separa bien lo estable de lo volátil, y la doc debe respetarlo. ¿Qué es estable en un sistema? Las intenciones y las fronteras: por qué existe payments, qué responsabilidad tiene, con qué habla y con qué no, qué garantías debe cumplir. Eso cambia poco porque es el "para qué" del sistema, y el para qué es lento. ¿Qué es volátil? Los detalles de implementación: qué funciones hay hoy, qué endpoints, qué parámetros. Eso cambia rápido porque es el "cómo" del momento, y el cómo se refactoriza constantemente. La doc que sobrevive documenta el "para qué" y las fronteras (estable, a mano) y deja el "cómo" del momento al código (volátil, generado o leído directo). Un dev nuevo que entiende el para qué y las fronteras puede leer el cómo en el código sin problema; un dev nuevo que solo tiene una lista de endpoints obsoleta no entiende nada y encima lo mandan por el camino equivocado.

El matiz honesto, para no volver esto una excusa para no documentar nada. "No documentes lo volátil a mano" no es "no documentes lo volátil": es "no lo documentes a mano". La lista de endpoints sí debe existir —es útil—, pero generada desde el router, no tecleada en una wiki. Las reglas de negocio sí deben estar documentadas —pero idealmente como tests que las verifican (que no se pueden pudrir), más una nota del porqué—. La distinción no es entre "documentar" y "no documentar"; es entre "escribir a mano" (solo lo estable) y "generar desde la fuente" (lo volátil). El error que combate la lección no es documentar lo volátil, sino documentarlo a mano, que es lo que garantiza el ROI negativo y la putrefacción. Y el otro error, simétrico, es no documentar lo estable —dejar el porqué de payments solo en la cabeza de Elena porque "el código habla por sí mismo"—: el código no explica el porqué, y ese porqué estable es justo lo de ROI más alto y lo que sube el bus factor (lección 7).

Errores comunes

Documentar de más lo volátil (el post-it del menú). Qué pasa: el equipo, queriendo ser exhaustivo, documenta a mano cada endpoint, cada firma, cada valor de configuración —lo más concreto y visible—, y como eso cambia constantemente, la doc queda obsoleta en semanas y se vuelve una trampa. Por qué pasa: lo volátil es lo más tangible ("aquí está la lista completa de endpoints" se siente como documentación de verdad), mientras que lo estable (el porqué) se siente abstracto y menos "documentable". Cómo detectarlo: si tu doc lista detalles de implementación que cambian cada sprint, o si "mantener la doc al día" se siente como una tarea infinita, estás documentando lo volátil a mano. Cómo corregirlo: generar lo volátil desde el código (OpenAPI para endpoints, análisis de dependencias para diagramas de detalle, tests para reglas) y reservar la escritura a mano para lo estable; el ROI negativo de lo volátil-a-mano se vuelve positivo cuando se genera.

Documentar de menos lo estable (dejar el porqué en una cabeza). Qué pasa: el equipo no documenta las decisiones ni las fronteras "porque el código habla por sí mismo", y el porqué de cada cosa vive solo en la cabeza de quien la decidió. Cuando esa persona se va, el porqué se va con ella, y el equipo deshace decisiones sin entender su razón. Por qué pasa: lo estable —sobre todo el porqué— es lo que no está en el código, así que es fácil olvidar que hay que escribirlo; y como cambia poco, no hay una presión constante que recuerde su ausencia. Cómo detectarlo: si nadie puede explicar por qué payments está separado sin preguntarle a Elena, o si las decisiones importantes no tienen ADR, estás documentando de menos lo estable. Cómo corregirlo: escribir los ADRs de las decisiones significativas y documentar las fronteras (el C4 y los límites); es lo de ROI más alto (churn bajo, se lee por años) y lo que sube el bus factor. El código muestra el qué; el porqué hay que escribirlo.

Decidir qué documentar por importancia en vez de por volatilidad. Qué pasa: el equipo prioriza documentar "lo más importante" y termina documentando a mano cosas importantes pero volátiles (la lista de endpoints es importante), gastando esfuerzo en doc que se pudre, mientras deja sin documentar cosas estables porque parecían "menores". Por qué pasa: la importancia es la heurística intuitiva ("documentemos lo que más importa"), pero es la heurística equivocada para esta decisión. Cómo detectarlo: si justificas documentar algo a mano diciendo "es que es muy importante" sin considerar cuánto cambia, estás usando la variable equivocada. Cómo corregirlo: antes de documentar algo a mano, preguntar primero "¿cambia poco?" (volatilidad) y solo después "¿ayuda?" (importancia); lo importante-y-volátil se genera, lo importante-y-estable se escribe, y lo no-importante no se documenta de ninguna forma. La importancia decide si la información debe estar disponible; la volatilidad decide cómo (a mano o generada).

Ejercicios

Ejercicio 1 — Por qué lo importante puede tener ROI negativo. En el ejemplo, api_endpoint_list es información útil (la gente la lee) y sin embargo tiene ROI negativo (−14h), mientras que key_decisions tiene ROI positivo (+29h). Un ingeniero dice: "pero los endpoints son más importantes para el día a día que las decisiones de arquitectura, deberíamos documentarlos con prioridad". Explica por qué su razonamiento confunde dos variables, y qué debería hacer con los endpoints.

Ver solución

El ingeniero confunde importancia con volatilidad, que son dos variables distintas que afectan cosas distintas del ROI. La importancia sube el beneficio (información importante se lee más y ahorra más); la volatilidad sube el costo de mantenimiento (información que cambia mucho hay que actualizarla mucho). Los endpoints pueden ser muy importantes —y por eso tienen algún beneficio (6h)— pero cambian 40 veces al año, así que mantenerlos sincronizados a mano cuesta 20h al año, más de lo que rinden. El ROI es negativo no a pesar de que sean importantes, sino porque son volátiles: aunque fueran aún más importantes, su volatilidad seguiría haciendo que documentarlos a mano cueste más de lo que rinde. La importancia no puede salvar a lo volátil, porque no toca la variable que hunde el ROI (el costo).

Lo que debería hacer con los endpoints no es documentarlos a mano ni dejarlos sin documentar —los dos extremos son errores—. Debería generarlos desde el código: un OpenAPI (o equivalente) que sale del router y se actualiza solo cuando el código cambia. Eso mantiene la información disponible (satisface la importancia) con costo de mantenimiento cero (elimina el problema de la volatilidad), convirtiendo el ROI negativo de documentar-a-mano en un ROI positivo de generar. La regla: cuando algo es importante-pero-volátil, la respuesta no es la wiki ni el olvido, es la generación desde la fuente. La importancia dice que la información debe existir; la volatilidad dice que debe generarse, no teclearse.

Ejercicio 2 — Clasifica y decide. Para cada una de estas cinco piezas de información sobre payments, di si es estable o volátil, y qué harías con ella (documentar a mano / generar desde el código / dejar en su fuente): (a) por qué payments cobra por cola en vez de escritura directa; (b) los nombres exactos de las columnas de la tabla de transacciones; (c) qué otros módulos pueden llamar a payments y cuáles no (la frontera); (d) la versión actual de la librería del proveedor de pagos; (e) qué atributo de calidad debe cumplir payments (por ejemplo, procesar picos sin caerse).

Ver solución

• (a) Por qué payments cobra por cola → ESTABLE, documentar a mano (ADR). Es una decisión con su porqué; cambia rarísima vez (solo si se revisa la decisión) y no está en el código (el código muestra que hay cola, no por qué). ROI alto: escrita una vez, útil por años, sube el bus factor. Va a mano, en un ADR.
• (b) Nombres de columnas de la tabla → VOLÁTIL, dejar en su fuente (el código/esquema). Las columnas se refactorizan seguido (se añaden, renombran, quitan). Documentarlas a mano se pudre; viven en el esquema de la base de datos y en el código, que son la fuente de verdad y están siempre al día. Se leen ahí, o se generan del esquema; no se documentan a mano.
• (c) La frontera: quién puede llamar a payments → ESTABLE, documentar a mano (C4 + posiblemente un ADR). La frontera de un módulo —su responsabilidad y con qué habla— es de lo más estable que hay: es el "para qué" del módulo, cambia poco. Y es crítica para que nadie la viole por accidente. Va a mano, en el C4 y en la descripción de límites; churn bajo, ROI alto.
• (d) Versión de la librería del proveedor → VOLÁTIL, dejar en su fuente (el archivo de dependencias). La versión cambia con cada actualización; documentarla a mano en una wiki garantiza que quede obsoleta. Vive en el archivo de dependencias (package.json, requirements.txt, etc.), que es la fuente de verdad. No se documenta a mano.
• (e) El atributo de calidad que payments debe cumplir → ESTABLE, documentar a mano (arc42 sección de calidad / ADR). Los atributos de calidad —derivados de metas de negocio en el módulo 5— cambian poco: son garantías que el sistema debe sostener. Y no están en el código de forma explícita. Van a mano, en la sección de calidad de arc42 o en un ADR; churn bajo, alto valor para quien diseña o modifica payments.

El patrón: lo que es por qué / para qué / frontera / garantía es estable y va a mano (y suele no estar en el código); lo que es detalle de implementación del momento (columnas, versiones) es volátil y vive en su fuente. La pregunta "¿cambia poco?" separa las dos limpiamente.

Ejercicio 3 — La línea que se mueve. El ROI de documentar algo a mano depende de su churn. Imagina que la lista de endpoints de Mercado, que hoy tiene churn 40 (ROI −14h a mano), se estabilizara —porque la API se congeló para clientes externos y ya casi no cambia, digamos churn 3—. ¿Cambiaría la decisión de generarla vs documentarla a mano? Piensa con la lógica del ROI y di qué te enseña esto sobre la regla.

Ver solución

Sí, cambiaría, y esto revela algo importante sobre la regla. Con churn 40, el costo de mantenimiento de la lista de endpoints a mano era 40 × 0.5h = 20h al año, contra un beneficio de 6h → ROI −14h (no vale documentarla a mano, hay que generarla). Si la API se congela y el churn baja a 3, el costo de mantenimiento cae a 3 × 0.5h = 1.5h al año, contra el mismo beneficio de 6h → ROI ≈ +4.5h (ahora sí valdría documentarla a mano, porque casi no cambia). La misma información —la lista de endpoints— pasa de "genera desde el código" a "podrías documentarla a mano" solo porque su volatilidad cambió.

Lo que esto enseña es que estable y volátil no son categorías fijas de tipos de información, sino una propiedad del churn en un contexto dado. "Lista de endpoints" no es inherentemente volátil: es volátil mientras la API cambia seguido, y se vuelve estable cuando la API se congela. La regla "documenta lo estable, no lo volátil" se aplica mirando el churn real de cada cosa en tu sistema, no una etiqueta universal. Un endpoint de una API pública congelada (contrato con clientes externos, no se puede cambiar sin romperlos) es estable y vale documentarlo; un endpoint interno que se refactoriza cada semana es volátil y hay que generarlo. La lección práctica: antes de decidir cómo documentar algo, mide (o estima) cuánto cambia de verdad en tu contexto, en vez de asumir. Y dicho esto, incluso cuando lo volátil se estabiliza y se podría documentar a mano, generarlo desde el código sigue siendo más seguro si es posible —porque el churn podría volver a subir, y la generación nunca se pudre—. La regla del churn dice cuándo documentar a mano es viable; la de living documentation dice que, cuando se pueda generar, generar es aún mejor.

Resumen y siguiente paso

En esta lección aprendiste la regla que salva la doc del olvido: documenta lo estable, no lo volátil. Viste, con el manual de la casa contra el post-it del menú, que documentar lo estable (la llave de paso) es una inversión que rinde por años con un solo pago, mientras documentar lo volátil (el menú) es un gasto recurrente que rinde poco y siempre está a punto de mentir. Y lo mediste con el ROI: las tres piezas estables (decisiones, límites, cómo correrlo) tienen ROI positivo; las tres volátiles (endpoints, firmas, estado) tienen ROI negativo —y descubriste que la variable que voltea el signo es el churn, no la importancia—. Aprendiste la frontera práctica: lo estable se escribe a mano (barato de mantener, y a menudo el porqué no está en el código); lo volátil se genera desde su fuente (costo de mantenimiento cero, siempre al día); y que "no documentes lo volátil a mano" no es "no lo documentes" —es generarlo, no teclearlo—.

Antes de avanzar deberías poder: explicar por qué información importante puede tener ROI negativo (la volatilidad sube el costo, no la importancia); clasificar piezas de doc en estable/volátil y decidir a mano/generar/dejar-en-fuente; y entender que estable/volátil depende del churn real, no de una etiqueta fija.

La lección 6 baja a una pieza concreta y estable que todo sistema necesita y casi nadie hace bien: el README que hace onboarding. Es el primer contacto del dev nuevo con el sistema —qué hace, cómo correrlo, dónde están las piezas, cómo contribuir— y es de lo más estable que existe (cambia poco, se lee siempre), así que tiene ROI altísimo. Vas a ejecutar el costo de onboarding —el tiempo hasta el primer commit útil— con un buen README y sin él, y a ver por qué un README que de verdad permite arrancar el proyecto convierte días de sufrimiento en horas. La regla de esta lección dice que el README vale la pena documentarlo; la próxima enseña a escribir el que funciona.

Recursos

• Cyrille Martraire, Living Documentation (Addison-Wesley, 2019), sobre "stable knowledge" — el desarrollo canónico de la idea de esta lección: documentar el conocimiento estable (que cambia despacio) y derivar lo volátil de la fuente. En inglés.
• Martin Fowler — "Who Needs an Architect?" y el hub de arquitectura — Fowler define la arquitectura como "las decisiones difíciles de cambiar", que es justo lo estable: lo que más vale la pena documentar porque es lo que más perdura. En inglés.
• Andrew Hunt y David Thomas, The Pragmatic Programmer, 20th Anniversary Edition (Addison-Wesley, 2019), principio DRY y "the evils of duplication" — por qué documentar a mano lo que ya está en el código (lo volátil) crea una duplicación que garantiza la desincronización. En inglés.
• Simon Brown — sobre qué documentar y qué no (c4model.com y sus charlas) — la idea de documentar la estructura y las intenciones estables, y dejar el detalle volátil al código. En inglés.
• OpenAPI Specification — el ejemplo por excelencia de generar lo volátil desde la fuente: la lista de endpoints derivada del código, siempre al día, en vez de una lista tecleada a mano que se pudre. En inglés.