workspace-v1/shared/knowledge-base/standards/ESTANDAR-ESTRUCTURA-DOCUMENTACION.md

Estándar de Estructura de Documentación

Objetivo

Definir la estructura estándar para la documentación de proyectos dentro del workspace, basada en las mejores prácticas del proyecto Gamilit.

---

Estructura de Carpetas docs/

Principio de Numeración

La numeración sigue un esquema jerárquico:

• 00-09: Visión general y contexto
• 01-0N: Fases del proyecto (secuenciales)
• 90-99: Documentación transversal y referencia

docs/
├── 00-vision-general/           # Visión, arquitectura, contexto
├── 01-fase-{nombre}/            # Primera fase del proyecto
├── 02-fase-{nombre}/            # Segunda fase del proyecto
├── ...                          # Fases adicionales según necesidad
├── 0N-fase-{nombre}/            # N-ésima fase
│
├── 90-transversal/              # Documentación que cruza todas las fases
├── 95-guias-desarrollo/         # Guías técnicas de desarrollo
├── 96-quick-reference/          # Referencias rápidas (cheatsheets)
├── 97-adr/                      # Architecture Decision Records
├── 98-standards/                # Estándares del proyecto
├── 99-finiquito/                # Documentación de cierre/entrega
│
├── {feature-especifica}/        # Carpetas de features sin numeración
└── README.md                    # Índice maestro de documentación

---

Reglas de Numeración

Fases del Proyecto (01-0N)

Las fases representan etapas cronológicas o lógicas del proyecto:

Prefijo	Uso	Ejemplo
01-fase-	Primera fase	01-fase-alcance-inicial/
02-fase-	Segunda fase	02-fase-robustecimiento/
03-fase-	Tercera fase	03-fase-extensiones/
04-fase-	Fase de backlog	04-fase-backlog/

Nomenclatura: {NN}-fase-{nombre-descriptivo}/

Documentación Transversal (90-99)

Reservada para documentación que no pertenece a una fase específica:

Prefijo	Propósito
90-transversal/	Cruza todas las fases (APIs, BD, componentes)
95-guias-desarrollo/	Guías técnicas para desarrolladores
96-quick-reference/	Cheatsheets, referencias rápidas
97-adr/	Architecture Decision Records
98-standards/	Estándares y convenciones del proyecto
99-finiquito/	Manuales de usuario, entrega final

Carpetas sin Numeración

Para features o módulos específicos que no son fases:

├── sistema-recompensas/         # Feature específica
├── student-portal/              # Portal específico
├── database/                    # Documentación de BD
└── frontend/                    # Documentación de frontend

---

Estructura Interna de Fases

Cada fase debe contener:

01-fase-{nombre}/
├── README.md                    # Índice de la fase
├── _MAP.md                      # Mapa de archivos (opcional)
├── {EPICA-001}/                 # Épica o feature principal
│   ├── README.md
│   ├── requerimientos/
│   │   └── US-{XXX}-{nombre}.md
│   ├── especificaciones/
│   │   └── SPEC-{nombre}.md
│   └── implementacion/
│       └── IMPL-{nombre}.md
└── {EPICA-002}/
    └── ...

---

Archivo README.md Principal

El README.md de docs/ debe incluir:

1. Encabezado del Proyecto

   • Nombre, versión, período, estado

2. Alcance (MVP vs Backlog)

   • Tabla clara de qué está incluido vs pendiente

3. Mapa de Navegación

   • Árbol de estructura con descripción de cada carpeta

4. Resumen por Fase

   • Objetivo, épicas, resultados, métricas

5. Navegación por Dominio

   • Acceso rápido por área funcional

6. Métricas y Estado

   • Completitud, coverage, KPIs

---

Ejemplos por Tipo de Proyecto

Proyecto con Fases Cronológicas (Gamilit)

docs/
├── 00-vision-general/
├── 01-fase-alcance-inicial/     # Mes 1
├── 02-fase-robustecimiento/     # Mes 2
├── 03-fase-extensiones/         # Mes 3-4
├── 04-fase-backlog/             # Futuro
├── 90-transversal/
├── 95-guias-desarrollo/
├── 96-quick-reference/
├── 97-adr/
├── 98-standards/
└── 99-finiquito/

Proyecto con Módulos (ERP)

docs/
├── 00-vision-general/
├── 01-modulo-contabilidad/
├── 02-modulo-inventarios/
├── 03-modulo-ventas/
├── 04-modulo-compras/
├── 90-transversal/
├── 95-guias-desarrollo/
├── 97-adr/
└── 98-standards/

Proyecto Nuevo (Minimal)

docs/
├── 00-vision-general/
│   └── README.md                # Visión inicial
├── 01-fase-mvp/
│   └── README.md                # Pendiente de definir
├── 95-guias-desarrollo/
│   └── README.md
└── README.md

---

Anti-patrones

NO hacer:

1. Duplicar numeración

   # INCORRECTO
   ├── 01-requerimientos/
   ├── 01-fase-inicial/          # Conflicto de numeración
   

2. Mezclar niveles

   # INCORRECTO
   ├── 01-fase-inicial/
   ├── componentes/              # Sin numeración junto con numerados
   ├── 02-fase-desarrollo/
   

3. Numeración no secuencial

   # INCORRECTO
   ├── 01-fase-inicial/
   ├── 05-fase-final/            # Salto de numeración
   

SÍ hacer:

1. Numeración consistente

   # CORRECTO
   ├── 01-fase-mvp/
   ├── 02-fase-consolidacion/
   ├── 03-fase-expansion/
   

2. Features sin numerar van al final

   # CORRECTO
   ├── 01-fase-mvp/
   ├── 02-fase-consolidacion/
   ├── 90-transversal/
   ├── sistema-pagos/            # Feature específica
   └── integraciones/            # Feature específica
   

---

Migración de Proyectos Existentes

Cuando se migra documentación existente:

1. Identificar estructura actual
2. Mapear a la estructura estándar
3. Eliminar duplicados de numeración
4. Preservar contenido original
5. Actualizar referencias internas

---

Validación

El script validate-structure.sh verifica:

• Existencia de docs/README.md
• Carpeta docs/ presente
• Sin carpetas con numeración duplicada

---

Estándar basado en el proyecto Gamilit - Sistema NEXUS Última actualización: 2025-12-05