Cómo uso IA para escribir documentación técnica que no caduca

La documentación técnica es a menudo el primer elemento que se abandona en un proyecto, o el último en actualizarse. El resultado son manuales desfasados, APIs sin describir y configuraciones en producción que solo existen en la cabeza de quien las montó. Este problema no es por falta de voluntad, sino por la inversión de tiempo que requiere mantenerla al día.

En mis proyectos, he integrado la IA no para que escriba la documentación por completo, sino para que me asista en el proceso, garantizando que el contenido sea preciso, esté bien estructurado y, lo más importante, sea fácil de mantener.

El problema de la documentación que nadie actualiza

La documentación caduca porque el software evoluciona. Cada nueva funcionalidad, cada refactorización o cada cambio en la infraestructura deja obsoletas las instrucciones previas. Requiere un esfuerzo constante que muchos equipos no pueden o no quieren asumir.

Cuando un cliente me llega con un sistema indocumentado, el coste oculto de esa falta de claridad es enorme: onboarding lento, errores por interpretaciones incorrectas y una dependencia absoluta del conocimiento individual. Una buena documentación es una póliza de seguros contra la pérdida de contexto.

La IA en la generación de documentación: del borrador a la estructura

Mi regla es simple: la IA sirve como un acelerador para el borrador inicial y para estructurar la información. No le pido que invente, sino que organice lo que yo ya sé o lo que puede extraer de un código, un log o una configuración. Esto me permite dedicar mi tiempo a la revisión crítica y a añadir el contexto que solo un humano puede dar.

Por ejemplo, le puedo pasar un fragmento de código o una configuración de servidor y pedirle que genere una explicación inicial en Markdown. Esto no es solo una cuestión de velocidad; es también de consistencia. La IA no se olvida de secciones comunes ni de formatos estándar.

Claude y Markdown: mis herramientas para el trabajo

Uso Claude por su ventana de contexto amplia y su capacidad para seguir instrucciones complejas, algo fundamental cuando se trata de documentación técnica detallada. El formato de salida es casi siempre Markdown, porque es universal, ligero y se integra perfectamente en cualquier sistema de gestión de contenido o repositorio Git.

La diferencia entre una buena y una mala generación de documentación con IA no está en la herramienta, sino en el prompt. Necesitas ser específico sobre el público objetivo, el nivel de detalle, la estructura deseada y los ejemplos a incluir.

Un ejemplo de prompt que utilizo para documentar una API puede ser:

Eres un experto en API REST y documentación técnica.
Genera documentación en formato Markdown para el siguiente endpoint:

[PEGAR ESPECIFICACIÓN DEL ENDPOINT AQUÍ]

Considera que el público objetivo son desarrolladores que van a consumir esta API.
La documentación debe incluir:
1.  Descripción general del endpoint y su propósito.
2.  Método HTTP y URL.
3.  Parámetros de la solicitud (query, path, body) con tipo, si es requerido y descripción.
4.  Ejemplo de solicitud JSON.
5.  Respuestas posibles (200 OK, 400 Bad Request, 404 Not Found) con ejemplos de JSON.
6.  Errores comunes y su significado.

Este enfoque genera una base sólida que luego puedo refinar. Para documentación de código más general, como la que se necesita en proyectos solitarios, la IA ayuda a mantener una estructura coherente.

Lo que la IA no hace por ti: el criterio técnico

La IA es una herramienta de apoyo, no un sustituto del conocimiento. El criterio técnico para validar lo que genera es insustituible. La IA puede inventar parámetros, describir comportamientos incorrectos o malinterpretar un contexto. Siempre reviso cada línea generada.

Lo que ganas:

• Velocidad en el borrador: El 80% del trabajo de estructuración y lenguaje se acelera drásticamente.
• Consistencia de formato: La IA sigue las directrices de Markdown y estructura que le indiques, reduciendo la variabilidad.
• Actualizaciones más rápidas: Cuando un componente cambia, es más rápido regenerar la sección afectada y revisar que reescribirla desde cero.

Lo que complicas:

• Necesidad de validación constante: No puedes confiar ciegamente en el output, especialmente en detalles críticos.
• Coste por token: Generar documentación extensa puede incurrir en costes si no se optimizan los prompts y el uso de la ventana de contexto.
• Manejo de la privacidad: No le pases información sensible o propietaria si el modelo de IA no garantiza la privacidad de tus datos.

Para tareas más avanzadas, como crear asistentes de consulta sobre grandes volúmenes de texto, la combinación de IA con técnicas como el RAG y los embeddings es muy potente. He explorado cómo construir un asistente de documentación usando embeddings para facilitar el acceso a la información. Además, mi experiencia usando Claude en escenarios de infraestructura real me ha demostrado su validez en contextos técnicos.

La IA ha transformado la forma en que abordo la documentación técnica, pero siempre como copiloto. El conocimiento y la experiencia humana siguen siendo el motor. Si quieres ir más allá de los prompts básicos, te recomiendo que explores cómo crear prompts efectivos que te den resultados. Y, sobre todo, ten claro cómo validar el output de los LLM en producción para evitar sorpresas.