project-docs

Documentación completa del proyecto

Resumen

Este skill genera una documentación exhaustiva del proyecto en el directorio docs/. El objetivo es que cualquier persona que llegue al proyecto tenga contexto absoluto sin necesidad de preguntar: qué hace el proyecto, cómo funciona, cómo se configura, cómo se contribuye y por qué se tomaron las decisiones que se tomaron.

No se trata de documentar por documentar, sino de crear una referencia viva que reduzca el tiempo de onboarding y evite la pérdida de conocimiento cuando alguien deja el equipo.

Proceso

Paso 1: auditar la documentación existente

• Listar los ficheros de documentación actuales (README, docs/, wikis, comentarios de código).
• Identificar qué está documentado, qué falta y qué está desactualizado.
• Comprobar si hay decisiones de arquitectura sin documentar (ADRs pendientes).

Paso 2: crear la estructura base en docs/

Generar los siguientes documentos si no existen:

docs/
  README.md              -- índice de la documentación
  architecture.md        -- visión general de la arquitectura
  getting-started.md     -- guía de inicio rápido
  development.md         -- guía de desarrollo (setup, tests, linting)
  api/                   -- documentación de API (si aplica)
  decisions/             -- ADRs (Architecture Decision Records)

Paso 3: documentar cada sección

Para cada documento:

• architecture.md: componentes principales, flujo de datos, dependencias entre módulos, diagramas (Mermaid o texto). No repetir el código, explicar el diseño.
• getting-started.md: prerrequisitos, instalación, configuración, primera ejecución. Probarlo desde cero para verificar que funciona.
• development.md: cómo ejecutar tests, linting, formateo. Convenciones de código. Flujo de trabajo con Git.
• API: endpoints, parámetros, respuestas, códigos de error, ejemplos con curl.
• decisions/: un ADR por cada decisión no obvia. Formato: contexto, decisión, consecuencias.

Paso 4: enlazar desde el README

El README principal debe apuntar a docs/ para los detalles. El README es la puerta de entrada; la documentación completa está dentro.

Qué NO hacer

• No duplicar información que ya está en el código (JSDoc, docstrings). Referenciar, no copiar.
• No documentar lo obvio. Documentar lo que no es evidente leyendo el código.
• No crear documentación que nadie va a mantener. Mejor poco y actualizado que mucho y obsoleto.