Idea principal

Decir que el código es la fuente de verdad del producto se entiende espontáneamente como "la documentación ya no sirve". La oposición está mal colocada: no está entre el código y los documentos, está entre dos funciones que los documentos cumplen y que no se distinguen.

Un artefacto que describe dice lo que el producto hace: una página de soporte sobre una funcionalidad, un changelog, una especificación funcional del estado actual, una documentación comercial sobre lo que es posible. Todo eso es deducible del repositorio, luego regenerable, luego sin interés en mantenerse.

Un artefacto que explica dice por qué: los intercambios y los razonamientos que condujeron a una elección, la decisión de producto y las alternativas descartadas, la razón por la que una decisión sustituye a otra. Nada de eso está en el código, y nada lo recuperará. A lo que se añade lo que no se deduce de ningún repositorio porque viene de fuera: un compromiso contractual, una restricción regulatoria, un documento externo.

El criterio de selección no es, pues, la forma del artefacto ni su autor, sino la pregunta a la que responde. Un mismo documento puede además pertenecer a las dos, y debe entonces cortarse en vez de clasificarse.

El corte se practica hasta dentro de una ficha. En una ficha de objeto de producto, el cuerpo describe la realidad tal como está en el código y se regenera; el bloque de desviaciones sostiene el juicio — lo que diverge de lo que querríamos — y se mantiene. La regla que los mantiene separados es absoluta y se dice en una frase: una desviación nunca modifica el cuerpo de la ficha. Sin esa frontera escrita, la primera regeneración se lleva la parte que ha costado cara de producir, ya que es la única que no se encuentra en ningún otro sitio.

Capa aportada por "Escribí la ontología de un producto. Tres veces creí haber terminado." (2026-08-11).

Por qué es importante

Es lo que hace operable el desplazamiento hacia el código sin destrucción. Sin esa línea, eliges entre conservarlo todo — y pagar la divergencia — y tirarlo todo — y perder el porqué, cuya falta solo se ve en el momento en que alguien reabre una decisión.

También da una prueba que aplicar a cualquier documento de producto antes de decidir su destino: ¿contiene una frase que ninguna lectura del repositorio permitiría escribir?

Matices y límites

El corte es más nítido en teoría que al leer un documento real: una especificación mezcla permanentemente el comportamiento esperado y el motivo que lo hizo retener, a menudo en la misma frase.

Y lo que explica no está exento de caducidad. Un razonamiento conservado sigue atado a un contexto de época; no diverge del producto como lo hace una descripción, simplemente se vuelve menos pertinente sin que nada lo señale.

Preguntas abiertas

• ¿Qué capta, en una organización, las explicaciones en el momento en que se producen, si se dicen en reuniones y en revisiones de código más que se escriben?