Prompting para Documentacion

Documentacion Que los Desarrolladores Realmente Leen

La documentacion es la tarea que los desarrolladores mas odian escribir y la IA es posiblemente mejor haciendo -- cuando se hace el prompt correctamente. El problema con la mayoria de la documentacion generada por IA es que es verbosa, generica y se lee como si fue escrita por alguien que nunca ha usado el codigo. Buenos prompts de documentacion producen salida que es concisa, especifica y escrita desde la perspectiva de alguien que necesita usar el codigo ahora mismo.

La idea clave es que diferentes tipos de documentacion sirven a diferentes audiencias y requieren diferentes prompts. Una referencia de API necesita precision y completitud. Un README necesita claridad e instrucciones de inicio rapido. Los comentarios inline de codigo necesitan brevedad y contexto. Un changelog necesita precision y relevancia. Cada tipo requiere un enfoque de prompting diferente.

Documentacion de API

La documentacion de API necesita ser precisa, estructurada y basada en ejemplos. El mejor enfoque es dejar que la IA lea tus route handlers reales y genere docs desde el codigo fuente.

Genera documentacion REST API para los endpoints de usuario en
src/routes/users.ts.

Para cada endpoint, documenta:
- Metodo HTTP y URL (con parametros de ruta)
- Descripcion (una oracion: que hace)
- Requisito de autenticacion (cuales endpoints requieren JWT?)
- Esquema del cuerpo del request (con tipos y reglas de validacion)
- Esquema del cuerpo de respuesta (con ejemplo JSON)
- Respuestas de error (codigo de estado, formato de error, cuando ocurre)
- Rate limiting (si aplica)

Formato como Markdown con bloques de codigo para ejemplos de request/response.
Usa nuestra documentacion de API existente en docs/api/products.md como
referencia de estilo.

Para los ejemplos de request/response, usa datos realistas (no "string" o
"ejemplo").

Generacion OpenAPI/Swagger

Genera una especificacion OpenAPI 3.0 en YAML para los endpoints de
autenticacion en src/routes/auth.ts.

Endpoints a documentar:
- POST /api/auth/register
- POST /api/auth/login
- POST /api/auth/refresh
- POST /api/auth/logout
- GET /api/auth/me

Para cada endpoint, incluye:
- operationId (camelCase, descriptivo)
- summary y description
- requestBody con JSON schema (derivar de los schemas de validacion Zod en el codigo)
- responses para exito y todos los casos de error
- requisitos de seguridad (cuales endpoints necesitan el Bearer token?)

Usa $ref para schemas compartidos: UserResponse, AuthTokens, ErrorResponse.
Incluye la seccion components/schemas al final.

Referencia los schemas Zod en src/schemas/auth.ts para los tipos exactos de
campos y reglas de validacion.

Generacion de README

Los archivos README necesitan responder cinco preguntas rapidamente: Que es esto? Como lo instalo? Como lo uso? Como contribuyo? Donde obtengo ayuda?

Crea un README.md para nuestro proyecto de API Express.js.

Contexto del proyecto:
- API REST de e-commerce construida con Express.js, TypeScript, Prisma, PostgreSQL
- Corre en Docker para desarrollo, desplegada en AWS ECS en produccion
- 45 endpoints en 8 tipos de recursos (usuarios, productos, ordenes, etc.)
- Usa autenticacion JWT con refresh tokens

Secciones a incluir:
1. Titulo del proyecto y descripcion de un parrafo
2. Prerequisitos (Node 20+, Docker, PostgreSQL 15)
3. Inicio rapido (clonar, instalar, configurar env, ejecutar con Docker)
4. Variables de entorno (listarlas desde .env.example con descripciones)
5. Vision general de API (tabla de endpoints principales por recurso, sin docs completos)
6. Desarrollo (como ejecutar tests, lint, formatear, migraciones)
7. Despliegue (resumen breve, enlace a docs de deploy separados)
8. Contribuir (enlace a CONTRIBUTING.md)

Reglas de estilo:
- Usar bloques de codigo para todos los comandos
- Mantener cada seccion bajo 10 lineas (enlazar a docs detallados para mas)
- Usar una tabla para variables de entorno
- No incluir badges o shields (los agregaremos despues)

Documentacion Inline de Codigo

La documentacion inline -- JSDoc, docstrings, comentarios de codigo -- necesita ser concisa e informativa. La IA debe agregar documentacion que provea valor mas alla de lo que el codigo mismo comunica.

Mal prompt:

Agrega comentarios a este archivo

Esto produce comentarios como // incrementar contador arriba de counter++, que no agregan valor.

Buen prompt:

Agrega documentacion JSDoc a los metodos publicos en
src/services/OrderService.ts.

Reglas:
- Solo documentar metodos publicos (omitir helpers privados)
- Primera linea: que hace el metodo en una oracion
- @param: tipo y descripcion para cada parametro
- @returns: que devuelve el metodo, incluyendo posibles null/undefined
- @throws: listar cada tipo de error y cuando se lanza
- @example: incluir un ejemplo de uso para metodos complejos
- NO agregar comentarios dentro del cuerpo de los metodos (el codigo es suficientemente claro)
- NO agregar documentacion obvia (omitir getters/setters con nombres auto-explicativos)

Referencia de estilo: Seguir los patrones JSDoc en src/services/UserService.ts.

Enfocarse en documentar el "por que" y los casos extremos, no el "que" que
es obvio desde la firma de la funcion.

El Patron "Explica a un Nuevo Miembro del Equipo"

Para documentacion arquitectonica que explica como las piezas encajan:

Escribe una vision general tecnica de nuestro sistema de autenticacion como
si se lo explicaras a un desarrollador que acaba de unirse al equipo.

Cubre:
1. Como funciona el flujo de auth (login -> emision JWT -> refresh token -> logout)
2. Que archivos estan involucrados (lista cada uno con una descripcion de una linea)
3. Como el middleware protege las rutas (authMiddleware, roleMiddleware)
4. Como se almacenan los tokens (httpOnly cookies? localStorage? ambos?)
5. Como funcionan los refresh tokens y cuando expiran
6. Gotchas comunes que los nuevos desarrolladores encuentran (problemas de CORS, expiracion de tokens durante desarrollo)

El lector es un desarrollador de nivel medio que conoce Express.js y conceptos
de JWT pero nunca ha visto nuestra implementacion especifica.

Mantenlo bajo 500 palabras. Usa referencias al codigo (rutas de archivos,
nombres de funciones) pero no incluyas bloques de codigo completos. Esto
es un mapa, no un tutorial.

Especificacion de Estilo de Escritura Tecnica

Al generar cualquier documentacion, especificar el estilo de escritura previene que la IA produzca prosa inflada y corporativa.

Requisitos de estilo para toda la documentacion en esta sesion:
- Escribir en voz activa ("La funcion devuelve" no "El valor es devuelto por")
- Usar segunda persona ("tu" no "el usuario" o "uno")
- Mantener parrafos bajo 4 oraciones
- Incluir ejemplos de codigo para cada concepto (muestra, no solo cuentes)
- Usar "Nota:" para advertencias importantes en lugar de incrustarlas en parrafos
- Evitar palabras: "apalancar", "utilizar", "facilitar", "robusto", "transparente"
- Preferir palabras cortas sobre largas ("usar" no "utilizar", "iniciar" no "inicializar")
- Ser directo: "Esto falla cuando X" no "Cabe senalar que en ciertas
  circunstancias, esto potencialmente podria fallar cuando X"

Puedes incluir este bloque de estilo al inicio de una sesion de documentacion y referenciarlo para todos los prompts posteriores.

Documentacion Desde Codigo

Uno de los prompts de documentacion mas utiles le pide a la IA que explique codigo existente con propositos de documentacion.

Explica que hace el modulo src/middleware/rateLimit.ts y como se conecta con
el resto del sistema.

Formato:
1. Resumen de un parrafo (que hace y por que existe)
2. Como funciona (paso a paso, sin codigo, solo logica)
3. Configuracion (que variables de entorno u opciones controlan su comportamiento)
4. Dependencias (que otros modulos importa y por que)
5. Donde se usa (cuales rutas o cadenas de middleware lo incluyen)
6. Modos de fallo (que pasa cuando Redis esta caido? cuando se exceden los limites?)

Escribe esto como documentacion para el directorio docs/middleware/. La
audiencia es un desarrollador que necesita entender el rate limiter para
modificarlo o depurar un problema de rate limiting en produccion.

Generacion de Changelog

La IA puede generar entradas de changelog desde commits de git, pero necesitas especificar la audiencia y nivel de detalle.

Genera una entrada de changelog para la version 2.4.0 a partir de estos
commits:

[pegar salida de git log o lista de mensajes de commit]

Formato: Keep a Changelog (keepachangelog.com) con secciones:
- Added (nuevas funcionalidades)
- Changed (cambios a funcionalidad existente)
- Fixed (correcciones de bugs)
- Deprecated (funcionalidades a eliminar)
- Security (cambios relacionados con seguridad)

Reglas:
- Escribir para usuarios finales y consumidores de API, no desarrolladores
- Cada entrada es una oracion, comenzando con un verbo
- Agrupar commits relacionados en una sola entrada
- Omitir refactorizacion interna, cambios de tests y actualizaciones de CI
- Incluir el numero de PR en parentesis si esta disponible
- Resaltar cambios que rompen compatibilidad con prefijo **BREAKING:**
- Para cambios de API, mencionar los endpoints especificos afectados

Guias de Migracion

Cuando publicas cambios que rompen compatibilidad, la IA puede ayudar a generar guias de migracion:

Genera una guia de migracion para usuarios actualizando de v2.x a v3.0
de nuestra API.

Cambios que rompen compatibilidad:
1. Autenticacion: El header de Bearer token cambio de "X-Auth-Token" a
   "Authorization: Bearer <token>"
2. Paginacion: Cambio de basada en offset (?page=2&limit=20) a basada en
   cursor (?cursor=abc&limit=20)
3. Formato de respuesta: Todas las respuestas envueltas en envelope
   { data: ..., meta: ... }
4. Endpoints eliminados: DELETE /api/users/:id/sessions (usar POST /api/auth/logout)

Para cada cambio:
- Explicar que cambio y por que
- Mostrar la forma vieja (v2) y la nueva (v3) lado a lado
- Proveer un ejemplo de codigo mostrando la migracion
- Senalar cualquier caso extremo o gotcha

Audiencia: desarrolladores que integran con nuestra API. Estan ocupados y
quieren migrar rapidamente. Se conciso y practico -- no les importan nuestras
razones internas, solo que necesitan cambiar.

El Prompt de Revision de Documentacion

Despues de generar documentacion, revisala por precision y completitud:

Revisa la documentacion de API en docs/api/orders.md contra la implementacion
real en src/routes/orders.ts.

Verificar:
1. Endpoints faltantes (hay rutas en el codigo que no estan documentadas?)
2. Schemas de request/response incorrectos (la doc coincide con la validacion
   Zod real y la respuesta Prisma?)
3. Respuestas de error faltantes (todos los caminos de error estan documentados?)
4. Ejemplos desactualizados (los requests de ejemplo realmente funcionan
   contra el codigo actual?)
5. Requisitos de autenticacion faltantes (cuales endpoints necesitan auth
   pero no lo dicen en la doc?)

Para cada discrepancia, muestra el texto de la doc vs el comportamiento
real del codigo.

Este prompt atrapa el problema de documentacion mas comun: docs que eran precisos cuando se escribieron pero se han alejado de la implementacion. Ejecutar este prompt periodicamente mantiene tu documentacion honesta.