Trazabilidad de la documentación

Por qué es importante

Sin trazabilidad, resulta difícil confiar en la documentación.

Los lectores no pueden decir:

• si una declaración está actualizada
• si un comportamiento es intencional
• si un reclamo proviene de la especificación del producto o de un accidente de implementación
• si un artículo público refleja la dirección aprobada del producto

La trazabilidad es especialmente importante en el trabajo asistido por IA porque el contenido generado puede parecer seguro incluso cuando no está basado en la fuente correcta.

¿Cómo es la trazabilidad?

Una buena trazabilidad de la documentación suele incluir:

• una cadena de autoridad conocida
• referencias estables a documentos o especificaciones relevantes
• clara separación entre el estado actual y los planes futuros
• distinción explícita entre documentación canónica y estado de implementación
• mapas de fuentes o notas de evidencia para artículos públicos sustanciales

También es cada vez más útil cuando la documentación es lo suficientemente específica como para guiar el trabajo asistido por IA, no solo la interpretación humana.

Un modelo de autoridad simple

Un modelo útil es:

1. especificación del producto
2. guía de implementación
3. documentación del estado actual
4. comportamiento de demostración o implementación
5. pruebas y resultados de validación

Esto ayuda a los equipos a decidir qué artefacto debe responder a qué pregunta.

Escritura pública y trazabilidad

Los artículos públicos, ensayos y material educativo no deben depender de ningún archivo fuente que se encuentre cerca.

En cambio, deberían preferir documentación estable y referencias de especificaciones, y utilizar mapas fuente cuando las afirmaciones sean sustanciales.

Eso hace que la escritura pública sea más sostenible y menos frágil con el tiempo.

Trazabilidad tanto para agentes como para humanos

La trazabilidad no se trata sólo de ayudar a una persona a comprender de dónde proviene un reclamo. También ayuda a un agente de IA a determinar qué artefactos del repositorio deben guiar la acción.

Cuando la documentación establece claramente el orden del flujo de trabajo, las preferencias de herramientas, las limitaciones del entorno y los límites de autoridad, se vuelve utilizable como contexto operativo para los agentes, así como contexto explicativo para las personas.

Esto es importante porque los agentes a menudo actúan según las instrucciones cercanas más concretas. Traceable Markdown ayuda a que la instrucción correcta sea visible.

Let Books contexto

El repositorio Let Books ya admite la trazabilidad mediante:

• AGENTS.md
• AGENTS-Implementation.md
• README.md
• docs/README.md
• docs/blog/README.md
• docs/sources/README.md
• mapas fuente según docs/sources/

También contiene guías Markdown que funcionan como contexto operativo rastreable para el trabajo de los agentes, tales como:

• docs/android-debugging.md para la elección del flujo de trabajo de depuración móvil y el uso de herramientas
• docs/style-guide/publishing/ubuntu-tooling.md para herramientas esperadas y capacidades de verificación

Esta estructura ayuda al proyecto a tratar la documentación como un sistema respaldado por evidencia en lugar de un conjunto de notas sueltas.