Todo equipo tiene el doc que miente. El README que describe un paso de setup que se quitó hace un año. La página de arquitectura que muestra tres servicios cuando ya hay cinco. La guía de onboarding que manda a la gente nueva a un repo que se partió. Nadie lo escribió mal. Era verdad el día que se escribió, y luego el código se movió y el doc no.
La explicación de siempre es la disciplina. Si la gente actualizara los docs cuando cambia el código, los docs estarían bien. Es reconfortante y es falso. La documentación se pudre por una razón estructural, y ninguna cantidad de disciplina arregla un problema estructural mucho tiempo.
Por qué se pudren los docs, exactamente
Un doc tradicional es una segunda copia de la verdad. La verdad vive en el código, en la config, en el sistema que corre. El doc es un artefacto aparte, en un sitio aparte, que describe esa verdad en prosa. Los dos están conectados por exactamente una cosa: un humano acordándose de actualizar la segunda copia cuando cambia la primera.
Ese enlace es el defecto. Es manual, no es tarea explícita de nadie, y falla en silencio. Cuando alguien shipea un cambio y se olvida del doc, no se rompe nada, ningún test se pone rojo, no salta ninguna alerta. El doc solo se vuelve un poco menos verdad, en silencio, y sigue pareciendo autoritativo todo el tiempo. La putrefacción no es un evento que puedas cazar. Es el estado por defecto de cualquier artefacto cuyo único vínculo con la realidad es la memoria humana.
Por esto los arreglos estándar no funcionan. Una plantilla mejor sigue siendo una segunda copia. Un proceso de review más estricto sigue apoyándose en que los humanos se acuerden. Una wiki más mona es un sitio más bonito para la misma putrefacción. Estás optimizando la copia cuando el problema es que exista una copia siquiera.
La era de la IA lo agudiza en dos direcciones a la vez. Los agentes ahora leen tus docs como contexto y responden con total seguridad según lo que diga el doc, así que un doc podrido no solo despista a un fichaje nuevo, envenena a cada agente que se fía de él. Y los agentes escriben código más rápido de lo que ningún humano puede actualizar a mano la prosa que lo describe, así que el hueco entre código y doc se abre más rápido de lo que la disciplina vieja lo puede cerrar.
El arreglo es quitar la copia, no actualizarla más rápido
La documentación viva no es “documentación que se te da mejor mantener”. Es documentación con el humano-en-el-bucle sacado del camino de actualización. El doc deja de ser una segunda copia y pasa a ser una proyección de la primera.
El movimiento es derivar los docs del sistema en vez de escribirlos al lado. Si la descripción de tu API se genera desde las rutas y los tipos reales, entonces cuando una ruta cambia la descripción cambia, porque son el mismo hecho renderizado una vez. Si tu vista de arquitectura se lee del grafo de conocimiento del código real, el mapa de qué llama de verdad a qué, entonces un servicio nuevo aparece en la vista en cuanto aparece en el código, sin que nadie dibuje una caja. No hay una segunda copia que se desincronice, porque no hay una segunda copia. Está el sistema, y una vista de él.
Ser verdad deja de ser una tarea que sigues sin hacer y pasa a ser una propiedad de cómo se produce el doc. No te puedes olvidar de actualizar una proyección. Se actualiza porque lo que proyecta se actualizó.
No todo se puede derivar, y merece la pena ser claro con la línea. El qué y el cómo de un sistema, las rutas, la estructura de llamadas, las dependencias, la forma, se pueden leer del código. El porqué normalmente no, porque la razón por la que se tomó una decisión no es visible en el código que resultó de ella. Esa parte hay que capturarla a propósito, cuando se toma la decisión, y luego atarla al código que gobierna. Que es una disciplina distinta de escribir prosa a posteriori, y una duradera, porque se registra una vez en el momento en que el conocimiento existe en vez de reconstruirse después de memoria. Este es el mismo razonamiento detrás de un cerebro de producto que se mantiene solo: captura el porqué en el momento de la decisión, deriva todo lo demás del sistema.
Docs-as-code es una media tinta, y merece la pena entender por qué
El paso más común que dan los equipos hacia los docs vivos es docs-as-code: meter la documentación en el repo, en markdown, junto al código, revisada en los mismos pull requests. Es una mejora real. Los docs viajan con el código, pasan por review, y un diff al menos le da a alguien la oportunidad de notar que la prosa ahora está mal.
Pero mira qué arregla de verdad. Mueve la segunda copia más cerca de la primera y mejora las probabilidades de que un humano note el desfase. No quita la segunda copia, y no quita al humano. El fichero markdown que describe la arquitectura sigue siendo un artefacto paralelo escrito a mano que tiene que actualizar alguien que se acordó, en el mismo commit, bien. Docs-as-code hace la putrefacción más cazable. No la hace estructuralmente imposible. Sigues teniendo dos cosas que pueden discrepar, y sigues dependiendo de la disciplina para mantenerlas de acuerdo, solo que con más probabilidad de cazar un desliz en la review.
La documentación viva es el paso más allá de docs-as-code. Conserva la disciplina de-revisado-en-repo para la prosa que de verdad hay que escribir, el porqué, la intención, lo que ningún sistema puede derivar. Pero para todo lo que se puede leer del código, deja de escribir una copia paralela y renderiza una vista del sistema en su lugar. Docs-as-code es donde pones la copia en un buen sitio. La documentación viva es donde borras la copia de todo lo que no debería haber sido una copia.
Qué no es la documentación viva
No es prosa autogenerada que nadie lee. Un muro de texto escrito por máquina describiendo cada función no es documentación viva, es ruido con una fecha fresca. El valor no es que lo escribiera una máquina. El valor es que es una proyección fiel del sistema real, así que lo que dice es lo que es verdad.
Tampoco es un sustituto del criterio sobre qué merece la pena documentar siquiera. Derivar una vista de todo es fácil y casi siempre inútil. La habilidad está en elegir qué proyecciones importan, la superficie de la API, la arquitectura, el provenance del código a las decisiones, y dejar que esas se mantengan verdaderas solas mientras gastas tu atención de verdad en el porqué que ningún sistema puede derivar por ti. Poner la estructura correcta delante de lectores y agentes es la mitad de documentación del context engineering: no más texto, la proyección correcta.
Dónde encaja PaellaDoc
PaellaDoc trata la documentación como una proyección, no como un artefacto paralelo. Lee tu repo a un grafo en tu máquina y deriva las vistas de él, así que el mapa del sistema sigue al día según el sistema se mueve. Las partes que no se pueden derivar, las decisiones y sus razones, se capturan según pasan y se enlazan al código que gobiernan, así que el porqué se registra una vez y nunca se reconstruye. El resultado es documentación que es verdad por cómo está hecha, leída igual por la gente de tu equipo y por los agentes que hacen el trabajo.
¿Qué doc de tu equipo está mintiendo ahora mismo, y cuánto lleva mintiendo? Cuéntame en el foro.
Preguntas frecuentes
¿Por qué la documentación siempre se queda obsoleta?
Por una razón estructural, no por pereza. Un doc tradicional es una segunda copia de la verdad, en un sitio distinto del código y atada a él por una sola cosa: un humano acordándose de actualizarla. Ese enlace es manual, tarea de nadie, y falla en silencio, así que el doc se vuelve menos verdad sin dejar de parecer autoritativo.
¿Qué es la documentación viva?
Documentación con el humano sacado del camino de actualización. En vez de escribir los docs al lado del sistema, los derivas de él, así que una descripción de API generada desde las rutas reales cambia cuando cambia una ruta, y una vista de arquitectura leída del grafo del código muestra un servicio nuevo en cuanto existe. No hay segunda copia que se desincronice.
¿Es docs-as-code lo mismo que documentación viva?
No, docs-as-code es una media tinta. Meter markdown en el repo, revisado en pull requests, acerca la segunda copia al código y mejora las probabilidades de que un humano note el desfase. Pero la copia y el humano siguen ahí. La documentación viva es el paso más allá: para todo lo que se puede leer del código, borra la copia y renderiza una vista.
¿Qué no se puede derivar del código?
El porqué. El qué y el cómo, las rutas, la estructura de llamadas, las dependencias, la forma, se leen del código. La razón por la que se tomó una decisión no es visible en el código que resultó de ella, así que hay que capturarla a propósito cuando se toma y atarla al código que gobierna. Deriva todo lo demás; gasta tu atención en el porqué.