Toda documentación técnica empieza bien y muere igual: desactualizada, contradiciendo al código y erosionando la confianza del equipo. La IA puede escribirla en minutos, lo que agrava el problema si no se decide antes qué merece existir.
Sección 01
Qué documentar y qué no
Lo que cambia cada semana no debe documentarse en prosa: el código es la fuente. Lo que sí necesita texto son las decisiones —por qué se eligió esta base de datos, qué alternativas se descartaron— porque eso no se deduce leyendo funciones.
Un registro breve de decisiones, con fecha y contexto, envejece bien. Un manual que describe paso a paso una interfaz que cambiará el mes que viene, no.
Sección 02
Generación asistida con contexto real
Para que la salida sea útil, el modelo necesita ver el código y las pruebas, no solo los nombres de los archivos. Las pruebas son la mejor documentación del comportamiento esperado.
Pide siempre ejemplos ejecutables. Un fragmento que se puede copiar y correr vale más que tres párrafos explicativos.
Sección 03
Mantenerla viva
Ata la documentación al flujo de trabajo: si un cambio toca una interfaz pública, la revisión debe incluir la actualización del texto. La IA propone el borrador; la persona lo aprueba.
Marca cada documento con la fecha de última verificación. Saber que algo se revisó hace catorce meses ya es información importante para quien lo lee.
Preguntas frecuentes
Lo que más se pregunta
Seguir leyendo
