IX. Hacia una Documentación Resiliente a la Teoría
Si tomamos a Naur en serio mientras reconocemos los cambios genuinos (aunque limitados) que la IA habilita, ¿qué prácticas se derivan?
Documentar Teoría, No Solo Artefactos
Junto con (o en lugar de) especificaciones y referencias de API, mantener documentos que aborden:
- Por qué el sistema está estructurado como está
- Qué alternativas fueron consideradas y rechazadas
- Cuándo los patrones deben y no deben aplicarse
- Cómo el sistema se relaciona con el mundo que modela
Estas son las preguntas que un sucesor hará. Responderlas antes de que sean formuladas.
Preservar el Diálogo
Tratar las transcripciones de colaboración con IA como artefactos documentales. Capturan el razonamiento en una forma más cercana a la observación del aprendizaje que a la documentación tradicional.
La transcripción muestra el proceso de resolución de problemas: los giros equivocados, las correcciones, el refinamiento gradual del entendimiento. Esto es material de transmisión de teoría.
Abrazar la Redundancia
La teoría se transmite a través de múltiples canales—prosa, diagramas, ejemplos, conversación. La redundancia no es desperdicio; proporciona múltiples puntos de entrada para lectores con diferentes antecedentes y estilos de aprendizaje.
Si un camino está bloqueado (el lector no entiende el diagrama), otros permanecen (la prosa, los ejemplos). La resiliencia proviene de la multiplicidad.
Probar la Transmisión de Teoría
La prueba definitiva de la documentación es si los nuevos miembros del equipo pueden adquirir suficiente teoría para hacer modificaciones correctas. Esto debe probarse explícitamente, no asumirse.
Preguntar: ¿puede alguien que solo tiene la documentación modificar este sistema correctamente? Si no, ¿qué falta?
Aceptar la Imperfección
La documentación nunca capturará completamente la teoría. El objetivo no es la perfección sino la suficiencia—proporcionar suficiente material para que un lector motivado pueda construir una teoría funcional.
Alguna pérdida en la transmisión es inevitable. El objetivo es minimizarla, no eliminarla.