Documentación y Compartir Conocimiento

La Documentación que Nadie Escribe

🔄 Repaso rápido: En la lección anterior, exploramos revisión de código y refactoring. Ahora pasemos a eso que todos saben que deben hacer pero nadie hace.

Pregúntale a cualquier equipo de desarrollo: “¿Su documentación está actualizada?” Mira cómo se ríen.

La documentación es el brócoli del desarrollo de software — todos saben que les hace bien, nadie quiere comerlo. El código se shipea, los features se lanzan, los docs… se agregan al backlog del próximo sprint. Que rueda al sprint siguiente. Que eventualmente se marca como “no se hará.”

La IA cambia esta ecuación fundamentalmente. No porque haga la documentación emocionante, sino porque la hace casi sin esfuerzo. Lo que antes tomaba una tarde ahora toma quince minutos.

Los Cinco Tipos de Documentación Dev

Cada tipo requiere un enfoque diferente con IA:

Documentación de API desde Código

Aquí es donde la documentación con IA realmente brilla:

Genera documentación de API para este endpoint.
Incluye: descripción, parámetros, ejemplos de
request/response, códigos de error y requisitos
de autenticación.

Framework: Express.js con TypeScript
Auth: Bearer token (JWT)

[pega el código del endpoint]
[pega los tipos de request/response]

Para un endpoint típico, la IA produce documentación estructurada completa con tablas de parámetros, ejemplos de request, respuestas de éxito, respuestas de error — todo en unos 10 segundos. Escribirlo manualmente tomaría 15-20 minutos por endpoint. Para una API con 30 endpoints, estás ahorrando un día entero.

Explicando Código Legacy

¿Heredaste un codebase sin documentación? Este es el momento de la IA.

Explica qué hace este código en lenguaje claro. Luego crea
un comentario de documentación para él. La audiencia es un
developer mid-level que se une a nuestro equipo.

[pega la función legacy enredada]

La IA produce explicaciones que incluyen no solo qué hace el código sino por qué — esa última parte frecuentemente es más valiosa.

✅ Revisión Rápida: ¿Cuál es el mayor riesgo de la documentación generada por IA, y cómo lo mitigas?

Generación de README

Para proyectos nuevos o repos que nunca tuvieron un README apropiado:

Genera un README.md para este proyecto basándote en su
estructura.

El árbol de directorios:
[pega output del comando tree]

El package.json (o requirements.txt, go.mod, etc.):
[pega archivo de dependencias]

El archivo de configuración principal:
[pega config]

Incluye: descripción del proyecto, prerrequisitos,
instrucciones de setup, correr localmente, correr tests,
deployment y resumen de la estructura del proyecto.

La IA produce un README completo que nuevos miembros del equipo pueden realmente seguir. La clave es proporcionar los archivos reales del proyecto — la IA extraerá los comandos de setup, dependencias y configuración correctos de archivos reales en vez de adivinar.

Documentación de Arquitectura

Esto requiere un enfoque colaborativo. La IA no puede conocer tu arquitectura solo del código — necesita tu guía sobre el “por qué.”

Ayúdame a documentar nuestra arquitectura de sistema.
Yo describo el diseño de alto nivel y tú creas
documentación estructurada.

Sistema: Procesamiento de pedidos e-commerce
Componentes:
- API Gateway (Express.js) - auth, rate limiting
- Servicio de Pedidos (Python) - lógica de negocio
- Servicio de Pagos (Go) - integración Stripe
- Servicio de Notificaciones (Node.js) - email, SMS, push
- PostgreSQL - pedidos, usuarios
- Redis - cache de sesiones, rate limiting
- RabbitMQ - comunicación async entre servicios

Crea documentación de arquitectura incluyendo:
1. Descripción del diagrama del sistema
2. Responsabilidades de cada componente
3. Patrones de comunicación
4. Flujo de datos para un pedido típico
5. Modos de falla y cómo se manejan

La IA crea la estructura y la prosa. Tú verificas la precisión y agregas el contexto que solo los humanos conocen — por qué se tomaron ciertas decisiones, qué trade-offs se consideraron, cuáles son los planes futuros.

Documentación Viva: Manteniendo los Docs Actualizados

Lo más difícil de la documentación no es crearla — es mantenerla al día. Estrategias con IA:

Chequeos de documentación en PRs: Pasa el diff y los docs actuales, pregunta si algo cambió que deba reflejarse.

Generación de changelog: Genera entradas de changelog desde los commits, escritas desde la perspectiva del usuario.

Actualizaciones de guía de onboarding: Compara tu guía actual contra cambios recientes al entorno de desarrollo.

Ejercicio Práctico

Elige uno de estos ejercicios:

1. Docs de API: Toma un endpoint de tu proyecto y genera documentación completa con IA. Compáralo con los docs existentes.

2. Explicación legacy: Encuentra la función más confusa de tu codebase. Haz que la IA la explique y genere un comentario de documentación.

3. Auditoría de README: Haz que la IA revise el README de tu proyecto contra la estructura real. Pregunta qué falta o está desactualizado.

Cada ejercicio debería tomar 5-10 minutos y ahorrarte horas de trabajo de documentación futuro.

Conclusiones Clave

• La IA hace la documentación casi sin esfuerzo — 15 minutos en vez de una tarde
• Proporciona código real para docs de API precisos, no descripciones del código
• Verifica docs generados por IA contra el comportamiento real — la IA a veces documenta comportamiento idealizado
• Usa la IA para explicar código legacy durante onboarding y transferencia de conocimiento
• Integra la documentación en tu flujo de PRs para que los docs se mantengan actualizados
• Los docs de arquitectura requieren colaboración — la IA estructura, tú verificas

Siguiente

En la Lección 7: Decisiones de Arquitectura y Diseño de Sistemas, aprenderás a usar la IA cuando te enfrentas a “¿microservicios o monolito?” y “¿qué base de datos le queda a nuestro caso de uso?” — razonando trade-offs con ayuda de IA.