Cómo documentar un proyecto de software web usando IA

Introducción

La documentación es una de las tareas más esenciales en el desarrollo de software, pero también una de las más tediosas y frecuentemente descuidadas. En 2025, la Inteligencia Artificial ha revolucionado completamente esta área, transformando lo que antes requería horas de trabajo manual en procesos automatizados y eficientes.

En este artículo aprenderás cómo aprovechar las herramientas de IA modernas para documentar tu proyecto web de forma profesional, completa y mantenible.

Tipos de documentación que necesita tu proyecto web

Antes de comenzar a documentar, es importante entender qué tipos de documentación requiere un proyecto de software web:

README y documentación de inicio

El README es la puerta de entrada a tu proyecto. Debe incluir:

• Descripción del proyecto y su propósito
• Requisitos y dependencias
• Instrucciones de instalación
• Comandos básicos para ejecutar el proyecto
• Estructura del proyecto
• Tecnologías utilizadas

Documentación técnica

Incluye aspectos más profundos del sistema:

• Documentación de API (endpoints, métodos, parámetros)
• Diagramas de arquitectura
• Modelos de datos y esquemas de base de datos
• Flujos de autenticación y autorización
• Integraciones con servicios externos

Guías de usuario

Orientadas a quienes usarán el sistema:

• Tutoriales paso a paso
• Casos de uso comunes
• Preguntas frecuentes (FAQ)
• Solución de problemas

Comentarios en el código

Documentación inline que explica:

• Lógica compleja de funciones
• Decisiones de diseño
• Parámetros y valores de retorno
• Advertencias y consideraciones especiales

Documentación de despliegue

Información crítica para poner el proyecto en producción:

• Configuración de entornos (desarrollo, staging, producción)
• Variables de entorno necesarias
• Proceso de CI/CD
• Instrucciones de rollback

Herramientas de IA para documentación

GitHub Copilot y Copilot Chat

GitHub Copilot no solo escribe código, también puede:

• Generar comentarios JSDoc automáticamente
• Explicar funciones complejas
• Sugerir descripciones para commits
• Crear documentación inline contextual

Claude y ChatGPT

Estos modelos de lenguaje son excelentes para:

• Generar README completos desde cero
• Crear documentación estructurada de APIs
• Traducir documentación técnica a lenguaje simple
• Generar historias de usuario
• Escribir guías paso a paso

Herramientas especializadas

• Mintlify: Genera documentación interactiva automáticamente
• Docusaurus: Framework para crear sitios de documentación (con plugins de IA)
• Swagger/OpenAPI: Documentación automática de APIs REST
• TypeDoc: Generación automática de docs para TypeScript
• JSDoc: Estándar para documentar código JavaScript

Extensiones de VS Code

• Comment Anchors: Organiza comentarios importantes
• Better Comments: Mejora la visualización de comentarios
• Document This: Genera documentación JSDoc automáticamente
• Markdown All in One: Facilita la escritura en Markdown

Workflow práctico: Paso a paso

Paso 1: Analizar tu código base con IA

Antes de documentar, es importante que la IA comprenda tu proyecto:

Prompt para Claude/ChatGPT:
"Analiza este proyecto web. Identifica:
- Stack tecnológico utilizado
- Arquitectura general
- Módulos principales
- Dependencias críticas
- Puntos que requieren documentación urgente"

Paso 2: Generar el README principal

Un buen README sigue esta estructura:

# Nombre del Proyecto

Breve descripción de lo que hace el proyecto.

## Características principales

- Característica 1
- Característica 2
- Característica 3

## Tecnologías

- Frontend: React 18, TypeScript, Tailwind CSS
- Backend: Node.js, Express, PostgreSQL
- Herramientas: Docker, GitHub Actions

## Instalación

### Requisitos previos

- Node.js 18+
- PostgreSQL 14+
- Docker (opcional)

### Pasos

1. Clonar el repositorio
git clone https://github.com/usuario/proyecto.git
cd proyecto

2. Instalar dependencias
npm install

3. Configurar variables de entorno
cp .env.example .env
# Editar .env con tus credenciales

4. Ejecutar migraciones
npm run migrate

5. Iniciar el servidor
npm run dev


## Uso

Ejemplos básicos de cómo usar el proyecto.

## Estructura del proyecto

proyecto/
├── src/
│   ├── components/
│   ├── services/
│   ├── utils/
│   └── index.js
├── tests/
├── docs/
└── README.md


## Contribuir

Instrucciones para contribuidores.

## Licencia

MIT License

Puedes usar IA para generar esto:

Prompt:
"Genera un README completo para mi proyecto web que usa:
- Frontend: React con TypeScript
- Backend: Node.js con Express
- Base de datos: MongoDB
- Incluye secciones de instalación, uso, y estructura"

Paso 3: Documentar APIs automáticamente

Para APIs REST, usa Swagger/OpenAPI:

/**
 * @swagger
 * /api/users/{id}:
 *   get:
 *     summary: Obtiene un usuario por ID
 *     parameters:
 *       - in: path
 *         name: id
 *         required: true
 *         schema:
 *           type: string
 *     responses:
 *       200:
 *         description: Usuario encontrado
 *       404:
 *         description: Usuario no encontrado
 */
app.get('/api/users/:id', getUserById);

Prompt para generar documentación de API:

"Documenta este endpoint de API en formato OpenAPI 3.0:
- Método: POST
- Ruta: /api/auth/login
- Body: { email: string, password: string }
- Respuesta exitosa: { token: string, user: object }
- Posibles errores: 400, 401, 500"

Paso 4: Crear diagramas de arquitectura con IA

Usa herramientas como Mermaid para crear diagramas:

graph TD
    A[Cliente Web] -->|HTTP Request| B[API Gateway]
    B --> C[Servicio de Autenticación]
    B --> D[Servicio de Usuarios]
    B --> E[Servicio de Pedidos]
    C --> F[(Base de Datos)]
    D --> F
    E --> F
    E --> G[Cola de Mensajes]
    G --> H[Servicio de Notificaciones]

Prompt:

"Genera un diagrama Mermaid que muestre la arquitectura de mi sistema:
- Frontend en React
- API Gateway
- Microservicios: Auth, Users, Orders
- Base de datos PostgreSQL
- Redis para caché
- RabbitMQ para mensajería"

Paso 5: Generar comentarios inline inteligentes

Para funciones complejas, la IA puede generar comentarios JSDoc:

/**
 * Calcula el precio final de un producto aplicando descuentos y impuestos
 * 
 * @param {number} basePrice - Precio base del producto
 * @param {Object} discount - Objeto con información del descuento
 * @param {string} discount.type - Tipo de descuento: 'percentage' o 'fixed'
 * @param {number} discount.value - Valor del descuento
 * @param {number} taxRate - Tasa de impuesto (ej: 0.16 para 16%)
 * @returns {number} Precio final calculado
 * @throws {Error} Si el precio base es negativo
 * 
 * @example
 * calculateFinalPrice(100, { type: 'percentage', value: 10 }, 0.16)
 * // Returns: 104.4
 */
function calculateFinalPrice(basePrice, discount, taxRate) {
  if (basePrice < 0) throw new Error('El precio no puede ser negativo');
  
  let priceAfterDiscount = basePrice;
  
  if (discount.type === 'percentage') {
    priceAfterDiscount = basePrice * (1 - discount.value / 100);
  } else if (discount.type === 'fixed') {
    priceAfterDiscount = basePrice - discount.value;
  }
  
  return priceAfterDiscount * (1 + taxRate);
}

Paso 6: Documentar funciones y componentes

Para componentes de React:

/**
 * Componente de tarjeta de producto
 * 
 * @component
 * @param {Object} props - Propiedades del componente
 * @param {string} props.title - Título del producto
 * @param {number} props.price - Precio del producto
 * @param {string} props.imageUrl - URL de la imagen
 * @param {Function} props.onAddToCart - Callback al agregar al carrito
 * 
 * @example
 * <ProductCard 
 *   title="Laptop"
 *   price={999.99}
 *   imageUrl="/images/laptop.jpg"
 *   onAddToCart={(id) => console.log(id)}
 * />
 */
export const ProductCard: React.FC<ProductCardProps> = ({
  title,
  price,
  imageUrl,
  onAddToCart
}) => {
  // Implementación
};

Integrando Conventional Commits

Los Conventional Commits son un estándar para escribir mensajes de commit estructurados que facilitan la generación automática de CHANGELOGs y el versionado semántico.

Estructura básica

<tipo>(<scope>): <descripción>

[cuerpo opcional]

[footer(s) opcional]

Tipos principales

• feat: Nueva funcionalidad
• fix: Corrección de bug
• docs: Cambios en documentación
• style: Formateo (sin cambios en lógica)
• refactor: Refactorización de código
• test: Agregar o modificar tests
• chore: Mantenimiento (dependencias, configs)
• perf: Mejoras de rendimiento
• ci: Cambios en CI/CD
• build: Cambios en build system

Ejemplos

feat(auth): agregar autenticación con JWT

Implementa sistema de tokens JWT para autenticación
- Agrega middleware de verificación
- Incluye refresh tokens
- Documenta endpoints en README

Closes #123

fix(api): corregir validación de email en registro

El regex anterior no validaba correctamente emails con subdominios

Fixes #456

docs(readme): actualizar instrucciones de instalación

Agrega sección sobre configuración de variables de entorno
y requisitos de versión de Node.js

Usando IA para generar commits

Prompt:

"Genera un mensaje de commit siguiendo Conventional Commits para estos cambios:
- Agregué un nuevo endpoint para eliminar usuarios
- Actualicé la documentación de la API
- El endpoint requiere rol de administrador"

Respuesta de IA:

feat(api): agregar endpoint para eliminar usuarios

Implementa DELETE /api/users/:id con verificación de rol admin

- Requiere autenticación y rol de administrador
- Actualiza documentación de API
- Agrega tests de autorización

Closes #234

Metodología CDE: Capture, Delegate, Edit

Para organizar el trabajo de documentación, puedes aplicar la metodología CDE:

Capture (Capturar)

Recopila todo lo que necesita documentación:

• Endpoints sin documentar
• Componentes complejos sin comentarios
• Funciones críticas sin JSDoc
• Configuraciones sin explicación
• Procesos de deployment no documentados

Herramientas:

• GitHub Issues para trackear items
• Notion para centralizar información
• Comentarios TODO en el código

// TODO: Documentar este algoritmo de optimización
// TODO: Agregar ejemplos de uso
// TODO: Explicar el parámetro 'threshold'
function optimizeQuery(query, threshold) {
  // Lógica compleja...
}

Delegate (Delegar)

Asigna responsabilidades:

• IA puede hacer: README básico, JSDoc, diagramas simples, ejemplos
• Humanos deben revisar: Arquitectura, decisiones de diseño, seguridad
• Colaboración IA + humano: Documentación de API, guías de usuario

Matriz de delegación:

Edit (Editar/Refinar)

Revisa y mejora la documentación generada:

1. Verificar precisión técnica: La IA puede alucinar o malinterpretar
2. Agregar contexto: Explicar el "por qué", no solo el "qué"
3. Mejorar ejemplos: Hacerlos más realistas y útiles
4. Actualizar regularmente: La documentación debe evolucionar con el código

Checklist de revisión:

- [ ] La información es técnicamente correcta
- [ ] Los ejemplos funcionan y son relevantes
- [ ] El lenguaje es claro y conciso
- [ ] Hay suficiente contexto para entender
- [ ] Los enlaces y referencias son válidos
- [ ] El formato es consistente
- [ ] No hay información sensible (claves, tokens)

Historias de Usuario: Documentación funcional

Las historias de usuario son una forma de documentar funcionalidades desde la perspectiva del usuario.

Estructura

Como [tipo de usuario]
Quiero [realizar alguna acción]
Para [obtener algún beneficio]

Ejemplo completo

# Historia #042: Recuperación de contraseña

## Descripción

Como usuario registrado que olvidó su contraseña
Quiero poder recuperarla mediante mi email
Para poder acceder nuevamente a mi cuenta sin contactar soporte

## Criterios de aceptación

- [ ] Existe un link "¿Olvidaste tu contraseña?" en la página de login
- [ ] El usuario ingresa su email registrado
- [ ] El sistema valida que el email existe en la BD
- [ ] Se envía un email con un link de recuperación válido por 1 hora
- [ ] El link redirige a un formulario para nueva contraseña
- [ ] La nueva contraseña debe cumplir requisitos de seguridad
- [ ] Se muestra mensaje de confirmación
- [ ] El usuario puede hacer login con la nueva contraseña
- [ ] Si el email no existe, se muestra mensaje genérico (seguridad)

## Tareas técnicas

- Crear endpoint POST /api/auth/forgot-password
- Implementar generación de token temporal
- Crear template de email
- Desarrollar UI del formulario
- Agregar tests unitarios y de integración

## Estimación

5 puntos

## Prioridad

Alta

## Sprint

Sprint 3

Usando IA para generar historias de usuario

Prompt:

"Genera 3 historias de usuario para un sistema de e-commerce:
1. Agregar productos al carrito
2. Aplicar cupones de descuento
3. Ver historial de pedidos

Incluye descripción, criterios de aceptación y tareas técnicas"

Modelo INVEST

Buenas historias de usuario cumplen con INVEST:

• Independent (Independiente): Se puede desarrollar sola
• Negotiable (Negociable): Flexible, no un contrato rígido
• Valuable (Valiosa): Aporta valor al usuario
• Estimable (Estimable): Se puede estimar el esfuerzo
• Small (Pequeña): Completable en un sprint
• Testable (Comprobable): Tiene criterios claros de éxito

Mejores prácticas y tips

Cómo escribir buenos prompts para documentación

❌ Prompt malo:

"Documenta mi código"

✅ Prompt bueno:

"Genera documentación JSDoc para esta función de JavaScript que calcula 
el precio final de un carrito de compras. Incluye:
- Descripción de la función
- @param para cada parámetro con tipo y descripción
- @returns con tipo y descripción
- @throws para posibles errores
- @example con al menos 2 ejemplos de uso"

✅ Prompt específico para README:

"Crea un README para mi API REST en Node.js con:
- Descripción breve del proyecto
- Stack tecnológico (Node.js 18, Express, MongoDB, JWT)
- Requisitos previos de instalación
- Pasos de instalación con comandos
- Variables de entorno necesarias
- Ejemplos de uso de los 3 endpoints principales
- Estructura de carpetas
- Instrucciones para ejecutar tests"

✅ Prompt para historias de usuario:

"Genera una historia de usuario para la funcionalidad de 'búsqueda avanzada 
de productos' en un e-commerce. Incluye:
- Formato 'Como [usuario] quiero [acción] para [beneficio]'
- 5-7 criterios de aceptación específicos
- Estimación en story points (escala Fibonacci)
- Tareas técnicas divididas entre frontend y backend"

Qué revisar y editar siempre manualmente

Nunca confíes ciegamente en la documentación generada por IA. Siempre revisa:

1. Información sensible: La IA podría incluir credenciales o datos privados del contexto
2. Precisión técnica: Verifica que los tipos de datos, parámetros y comportamientos sean correctos
3. Ejemplos funcionales: Prueba que los ejemplos de código realmente funcionen
4. Contexto del negocio: Agrega el "por qué" de las decisiones técnicas
5. Seguridad: Revisa que no se documenten vulnerabilidades o malas prácticas
6. Enlaces y referencias: Verifica que todos los links funcionen
7. Consistencia: Asegura que el tono y formato sean uniformes

Checklist de revisión de documentación

## Checklist de calidad

### Contenido
- [ ] Información técnicamente correcta
- [ ] Sin información sensible (keys, passwords, tokens)
- [ ] Ejemplos funcionan correctamente
- [ ] Incluye casos edge y errores comunes
- [ ] Explica el "por qué", no solo el "qué"

### Formato
- [ ] Markdown correctamente formateado
- [ ] Bloques de código con syntax highlighting
- [ ] Encabezados jerárquicos apropiados
- [ ] Listas con formato consistente

### Usabilidad
- [ ] Fácil de seguir para el público objetivo
- [ ] Tabla de contenidos para docs largas
- [ ] Enlaces internos funcionan
- [ ] Ejemplos son realistas y útiles

### Mantenibilidad
- [ ] Fecha de última actualización
- [ ] Versión del software documentada
- [ ] Información de contacto o contribución
- [ ] Issues/TODOs documentados

Mantener la documentación actualizada

La documentación desactualizada es peor que no tener documentación. Estrategias:

1. Documentación cercana al código

/**
 * IMPORTANTE: Si modificas esta función, actualiza también:
 * - docs/api/authentication.md
 * - README.md sección "Authentication Flow"
 */
async function authenticate(credentials) {
  // ...
}

2. Tests como documentación

describe('calculateFinalPrice', () => {
  it('debe aplicar descuento porcentual correctamente', () => {
    const result = calculateFinalPrice(100, { type: 'percentage', value: 10 }, 0.16);
    expect(result).toBe(104.4);
  });
  
  it('debe lanzar error con precio negativo', () => {
    expect(() => {
      calculateFinalPrice(-50, { type: 'fixed', value: 5 }, 0.16);
    }).toThrow('El precio no puede ser negativo');
  });
});

3. Hooks de Git

Crea un pre-commit hook que verifique documentación:

#!/bin/bash
# .git/hooks/pre-commit

# Verificar que archivos modificados tengan docs actualizadas
if git diff --cached --name-only | grep -q "src/api/"; then
  if ! git diff --cached --name-only | grep -q "docs/api/"; then
    echo "⚠️  Modificaste archivos en src/api/ pero no actualizaste docs/api/"
    echo "¿Continuar de todas formas? (y/n)"
    read -r response
    if [[ "$response" != "y" ]]; then
      exit 1
    fi
  fi
fi

4. CI/CD para documentación

# .github/workflows/docs.yml
name: Documentación

on:
  pull_request:
    paths:
      - 'src/**'
      - 'docs/**'

jobs:
  check-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      
      - name: Verificar links rotos
        run: |
          npm install -g markdown-link-check
          find docs -name "*.md" -exec markdown-link-check {} \;
      
      - name: Verificar ejemplos de código
        run: npm run test:docs-examples

5. Versionado de documentación

Para APIs, mantén documentación por versión:

docs/
├── v1/
│   ├── authentication.md
│   └── endpoints.md
├── v2/
│   ├── authentication.md
│   └── endpoints.md
└── latest/ -> v2/

Errores comunes al usar IA para documentar

1. Asumir que la IA siempre tiene razón

❌ Error:

/**
 * Genera un número aleatorio entre min y max (generado por IA)
 * @param {number} min - Valor mínimo
 * @param {number} max - Valor máximo
 * @returns {number} Número aleatorio
 */
function random(min, max) {
  return Math.floor(Math.random() * (max - min)) + min;
}

✅ Correcto (el código tiene un bug):

/**
 * Genera un número aleatorio entre min y max (inclusivo)
 * @param {number} min - Valor mínimo (inclusivo)
 * @param {number} max - Valor máximo (inclusivo)
 * @returns {number} Número entero aleatorio entre min y max
 */
function random(min, max) {
  return Math.floor(Math.random() * (max - min + 1)) + min; // +1 para incluir max
}

2. No proporcionar suficiente contexto

❌ Prompt sin contexto:

"Documenta esta función"

✅ Prompt con contexto:

"Documenta esta función que es parte de un sistema de pagos. 
Es crítica porque procesa transacciones financieras reales.
Los usuarios son desarrolladores externos que integran nuestra API.
Necesitan entender:
- Qué validaciones se hacen
- Qué errores pueden ocurrir
- Cómo manejar respuestas
- Ejemplos de uso en producción"

3. Copiar y pegar sin revisar

La IA puede generar:

• Información desactualizada
• Malas prácticas de seguridad
• Ejemplos que no funcionan
• Referencias a librerías que no usas

Siempre revisa y prueba.

4. Sobre-documentar

No todo necesita documentación exhaustiva:

❌ Over-documented:

/**
 * Suma dos números
 * @param {number} a - El primer número a sumar
 * @param {number} b - El segundo número a sumar
 * @returns {number} La suma de a y b
 * @example
 * add(2, 3) // Returns 5
 */
function add(a, b) {
  return a + b;
}

✅ Adecuado:

// Funciones simples y auto-explicativas no necesitan JSDoc
function add(a, b) {
  return a + b;
}

Reserva la documentación detallada para:

• Lógica compleja o no obvia
• APIs públicas
• Funciones con comportamientos especiales
• Código crítico para el negocio

5. Ignorar el público objetivo

Diferentes audiencias necesitan diferente nivel de detalle:

Para desarrolladores junior:

## Instalación paso a paso

1. Abre tu terminal
2. Navega a la carpeta donde quieres el proyecto:
   cd /ruta/a/tu/carpeta
3. Clona el repositorio:
   git clone https://github.com/usuario/proyecto.git
4. Entra a la carpeta:
   cd proyecto
...

Para desarrolladores senior:

## Quick Start

git clone https://github.com/usuario/proyecto.git && cd proyecto
npm install && cp .env.example .env
npm run migrate && npm run dev

Herramientas complementarias

Para generar documentación automática

• TypeDoc (TypeScript): Genera documentación HTML desde comentarios TSDoc
• JSDoc: Estándar para JavaScript
• Sphinx (Python): Si tienes microservicios en Python
• Swagger UI: Interfaz interactiva para APIs
• Redoc: Alternativa moderna a Swagger UI
• Postman: Genera documentación de colecciones de API

Para diagramas

• Mermaid: Diagramas como código (soportado en GitHub)
• PlantUML: UML como código
• Excalidraw: Diagramas dibujados a mano (exportables)
• Lucidchart: Herramienta visual colaborativa
• Draw.io: Gratuito y potente

Para sitios de documentación

• Docusaurus: Framework de Meta/Facebook
• VitePress: Basado en Vite, muy rápido
• MkDocs: Simple y efectivo (Python)
• GitBook: Comercial pero muy pulido
• Nextra: Basado en Next.js

Para mantener documentación actualizada

• Renovate: Actualiza dependencias automáticamente (incluye docs)
• markdown-link-check: Verifica links rotos
• Vale: Linter para documentación (estilo, gramática)
• alex: Detecta lenguaje insensible o no inclusivo

Ejemplo completo: Documentando una API REST

Veamos un ejemplo completo de cómo documentar una API de gestión de tareas:

1. README.md

# Task Manager API

API REST para gestión de tareas y proyectos.

## Stack

- Node.js 18+
- Express 4.18
- PostgreSQL 14
- JWT para autenticación
- Jest para testing

## Instalación

### Requisitos

- Node.js 18+
- PostgreSQL 14+
- npm o yarn

### Setup

bash
# Clonar repositorio
git clone https://github.com/usuario/task-api.git
cd task-api

# Instalar dependencias
npm install

# Configurar variables de entorno
cp .env.example .env
# Editar .env con tus credenciales

# Crear base de datos
npm run db:create

# Ejecutar migraciones
npm run migrate

# (Opcional) Cargar datos de prueba
npm run seed

# Iniciar servidor
npm run dev


El servidor estará disponible en `http://localhost:3000`

## API Endpoints

### Autenticación

#### POST /api/auth/register
Registra un nuevo usuario.

**Request:**
```json
{
  "email": "user@example.com",
  "password": "securePassword123",
  "name": "John Doe"
}

Response: 201 Created

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "uuid",
    "email": "user@example.com",
    "name": "John Doe"
  }
}

POST /api/auth/login

Inicia sesión.

Request:

{
  "email": "user@example.com",
  "password": "securePassword123"
}

Response: 200 OK

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "uuid",
    "email": "user@example.com",
    "name": "John Doe"
  }
}

Tareas

Todos los endpoints de tareas requieren autenticación mediante header:

Authorization: Bearer <token>

GET /api/tasks

Obtiene todas las tareas del usuario.

Query params:

• status (opcional): pending, completed, archived
• page (opcional): Número de página (default: 1)
• limit (opcional): Items por página (default: 20)

Response: 200 OK

{
  "tasks": [
    {
      "id": "uuid",
      "title": "Completar documentación",
      "description": "Escribir README completo",
      "status": "pending",
      "priority": "high",
      "dueDate": "2025-10-15T00:00:00Z",
      "createdAt": "2025-10-10T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 45,
    "pages": 3
  }
}

POST /api/tasks

Crea una nueva tarea.

Request:

{
  "title": "Nueva tarea",
  "description": "Descripción detallada",
  "priority": "medium",
  "dueDate": "2025-10-20"
}

Response: 201 Created

PUT /api/tasks/:id

Actualiza una tarea.

DELETE /api/tasks/:id

Elimina una tarea.

Testing

bash

Ejecutar todos los tests

npm test

Tests con coverage

npm run test:coverage

Tests en modo watch

npm run test:watch

Estructura del proyecto

task-api/ ├── src/ │ ├── controllers/ │ │ ├── authController.js │ │ └── taskController.js │ ├── middleware/ │ │ ├── auth.js │ │ └── errorHandler.js │ ├── models/ │ │ ├── User.js │ │ └── Task.js │ ├── routes/ │ │ ├── auth.js │ │ └── tasks.js │ ├── services/ │ │ └── emailService.js │ ├── utils/ │ │ └── validation.js │ ├── config/ │ │ └── database.js │ └── index.js ├── tests/ ├── docs/ ├── .env.example └── README.md

Variables de entorno

Copia .env.example a .env y configura:

env

Server

PORT=3000 NODE_ENV=development

Database

DB_HOST=localhost DB_PORT=5432 DB_NAME=taskmanager DB_USER=postgres DB_PASSWORD=tu_password

JWT

JWT_SECRET=tu_secret_muy_seguro JWT_EXPIRE=7d

Email (opcional)

SMTP_HOST=smtp.gmail.com SMTP_PORT=587 SMTP_USER=tu_email@gmail.com SMTP_PASS=tu_password

Contribuir

1. Fork el proyecto
2. Crea una rama para tu feature (git checkout -b feature/amazing-feature)
3. Commit tus cambios siguiendo Conventional Commits
4. Push a la rama (git push origin feature/amazing-feature)
5. Abre un Pull Request

Licencia

MIT

### 2. Código con JSDoc

```javascript
/**
 * Controlador para operaciones de tareas
 * @module controllers/taskController
 */

const Task = require('../models/Task');
const { validationResult } = require('express-validator');

/**
 * Obtiene todas las tareas del usuario autenticado
 * 
 * @async
 * @param {Object} req - Express request object
 * @param {Object} req.user - Usuario autenticado (inyectado por middleware)
 * @param {Object} req.query - Query parameters
 * @param {string} [req.query.status] - Filtrar por status: 'pending', 'completed', 'archived'
 * @param {number} [req.query.page=1] - Número de página
 * @param {number} [req.query.limit=20] - Items por página
 * @param {Object} res - Express response object
 * @returns {Promise<void>} JSON con tareas y metadata de paginación
 * 
 * @throws {500} Error de servidor si falla la consulta a BD
 * 
 * @example
 * // GET /api/tasks?status=pending&page=1&limit=10
 * // Response:
 * // {
 * //   "tasks": [...],
 * //   "pagination": { "page": 1, "limit": 10, "total": 45, "pages": 5 }
 * // }
 */
exports.getTasks = async (req, res) => {
  try {
    const { status, page = 1, limit = 20 } = req.query;
    const userId = req.user.id;

    // Construir filtros
    const filters = { userId };
    if (status) filters.status = status;

    // Calcular offset para paginación
    const offset = (page - 1) * limit;

    // Consultar tareas con paginación
    const { rows: tasks, count: total } = await Task.findAndCountAll({
      where: filters,
      limit: parseInt(limit),
      offset: parseInt(offset),
      order: [['createdAt', 'DESC']]
    });

    // Calcular metadata de paginación
    const pages = Math.ceil(total / limit);

    res.json({
      tasks,
      pagination: {
        page: parseInt(page),
        limit: parseInt(limit),
        total,
        pages
      }
    });
  } catch (error) {
    console.error('Error al obtener tareas:', error);
    res.status(500).json({ 
      error: 'Error al obtener tareas',
      message: process.env.NODE_ENV === 'development' ? error.message : undefined
    });
  }
};

/**
 * Crea una nueva tarea
 * 
 * @async
 * @param {Object} req - Express request object
 * @param {Object} req.body - Datos de la tarea
 * @param {string} req.body.title - Título de la tarea (requerido)
 * @param {string} [req.body.description] - Descripción detallada
 * @param {string} [req.body.priority='medium'] - Prioridad: 'low', 'medium', 'high'
 * @param {string} [req.body.dueDate] - Fecha límite (ISO 8601)
 * @param {Object} req.user - Usuario autenticado
 * @param {Object} res - Express response object
 * @returns {Promise<void>} JSON con la tarea creada
 * 
 * @throws {400} Si hay errores de validación
 * @throws {500} Error de servidor si falla la creación
 * 
 * @example
 * // POST /api/tasks
 * // Body: { "title": "Nueva tarea", "priority": "high" }
 * // Response: { "id": "uuid", "title": "Nueva tarea", ... }
 */
exports.createTask = async (req, res) => {
  try {
    // Validar request
    const errors = validationResult(req);
    if (!errors.isEmpty()) {
      return res.status(400).json({ errors: errors.array() });
    }

    const { title, description, priority = 'medium', dueDate } = req.body;
    const userId = req.user.id;

    // Crear tarea
    const task = await Task.create({
      title,
      description,
      priority,
      dueDate,
      userId,
      status: 'pending'
    });

    res.status(201).json(task);
  } catch (error) {
    console.error('Error al crear tarea:', error);
    res.status(500).json({ 
      error: 'Error al crear tarea',
      message: process.env.NODE_ENV === 'development' ? error.message : undefined
    });
  }
};

3. Historia de usuario

# Historia #015: Crear nueva tarea

## Descripción

Como usuario registrado
Quiero poder crear nuevas tareas con título, descripción y fecha límite
Para organizar mi trabajo y mantener seguimiento de mis pendientes

## Criterios de aceptación

- [ ] El usuario debe estar autenticado para crear tareas
- [ ] El campo título es obligatorio (máximo 200 caracteres)
- [ ] La descripción es opcional (máximo 2000 caracteres)
- [ ] Se puede asignar prioridad: low, medium, high (default: medium)
- [ ] Se puede establecer fecha límite opcional
- [ ] La tarea se crea con status 'pending' por defecto
- [ ] Se muestra mensaje de éxito tras crear la tarea
- [ ] La nueva tarea aparece inmediatamente en la lista
- [ ] Si hay error de validación, se muestran mensajes específicos

## Tareas técnicas

### Backend
- [ ] Crear endpoint POST /api/tasks
- [ ] Implementar validación de campos (express-validator)
- [ ] Crear modelo Task en Sequelize
- [ ] Agregar middleware de autenticación
- [ ] Escribir tests unitarios del controlador
- [ ] Escribir tests de integración del endpoint

### Frontend
- [ ] Crear componente CreateTaskForm
- [ ] Implementar validación de formulario en cliente
- [ ] Conectar con API usando fetch/axios
- [ ] Manejar estados de loading y error
- [ ] Actualizar lista de tareas tras crear
- [ ] Agregar tests del componente

### Documentación
- [ ] Documentar endpoint en README
- [ ] Actualizar collection de Postman
- [ ] Agregar ejemplos de uso

## Estimación

5 story points

## Prioridad

Alta

## Sprint

Sprint 2

## Notas técnicas

- Considerar rate limiting (máximo 100 tareas por usuario)
- Validar formato de fecha (ISO 8601)
- La fecha límite no puede ser en el pasado

Conclusión

Documentar proyectos de software ya no tiene que ser una tarea tediosa gracias a la IA. Al combinar herramientas como Claude, GitHub Copilot, y frameworks especializados, puedes:

• Reducir el tiempo de documentación en un 70-80%
• Mejorar la calidad con documentación más completa y consistente
• Mantener actualizada la documentación más fácilmente
• Enfocarte en lo importante: decisiones arquitectónicas y contexto de negocio

Recuerda los principios clave:

1. La IA es un asistente, no un reemplazo: Siempre revisa y valida
2. Contexto es crítico: Buenos prompts generan buena documentación
3. Metodología CDE: Captura, Delega, Edita
4. Conventional Commits: Mantén historial limpio y generación automática de CHANGELOGs
5. Historias de usuario: Documenta funcionalidad desde perspectiva del usuario
6. Documentación viva: Mantenla cerca del código y actualizada

Próximos pasos

1. Elige una herramienta de IA (Claude, ChatGPT, Copilot)
2. Identifica qué documentación te falta
3. Empieza con lo básico: un buen README
4. Itera y mejora continuamente
5. Automatiza lo que puedas (CI/CD, hooks)

La documentación excelente es una inversión que paga dividendos en:

• Onboarding más rápido de nuevos developers
• Menos tiempo respondiendo preguntas repetitivas
• Código más mantenible
• Mejor experiencia para usuarios de tu API

¡Empieza hoy mismo a documentar con IA y transforma tu proyecto!

Recursos adicionales

• Conventional Commits
• GitHub: Writing good documentation
• Markdown Guide
• JSDoc Documentation
• Swagger/OpenAPI Specification
• Docusaurus
• Write the Docs