📚 Estructura de Documentación

Esta guía define la estructura estándar de documentación para todos los proyectos del equipo, estableciendo un formato unificado que facilite el mantenimiento, la colaboración y la incorporación de nuevos miembros.

🎯 Objetivos

📏 Estandarizar

Documentación técnica y funcional con formato uniforme

🤝 Facilitar

Conocimiento interdepartamental y colaboración

⚡ Mejorar

Eficiencia en resolución de bugs y desarrollo de features

🚀 Acelerar

Curva de aprendizaje de nuevos integrantes

📁 Estructura Principal

📁 Productos
├── 📁 Web Tenant
│   ├── 📄 Descripción General
│   ├── 📁 Configuraciones y Feature Flags
│   ├── 📁 Reglas de Negocio
│   └── 📁 Arquitectura y Dependencias
└── 📁 [Otros Productos...]

📁 Proyectos
├── 📁 Web.Tenant
│   ├── 📄 Descripción General
│   ├── 📄 Setup del Proyecto
│   └── 📄 Arquitectura y Dependencias
├── 📁 Api.XXXX
│   ├── 📄 Descripción General
│   ├── 📄 Setup del Proyecto
│   └── 📄 Arquitectura y Dependencias
├── 📁 Vue.Inventory
│   ├── 📄 Descripción General
│   ├── 📄 Setup del Proyecto
│   └── 📄 Arquitectura y Dependencias
└── 📁 [Otros Proyectos...]

📁 Guía de Desarrollo
├── 📁 Frontend Vue.js
│   ├── 📁 Getting Started
│   │   ├── 📄 Setup del Entorno
│   │   ├── 📄 Quick Start
│   │   ├── 📄 Conceptos Clave
│   │   └── 📄 Decision Tree
│   ├── 📁 Templates y Scaffolding
│   ├── 📁 Desarrollo Día a Día
│   └── 📁 Arquitectura
├── 📁 Backend .NET
│   ├── 📁 .NET Core 8
│   └── 📁 Patrones y Mejores Prácticas
├── 📁 Bases de Datos
│   ├── 📄 SQL Server
│   └── 📄 Migraciones
├── 📁 DevOps y Deploy
│   ├── 📄 CI/CD Pipelines
│   ├── 📄 Environments
│   └── 📄 Monitoring
└── 📁 Procesos y Workflows
    ├── 📄 Code Review
    ├── 📄 Testing Strategies
    └── 📄 Documentation Standards

📊 Estado de Implementación

✅ Secciones Implementadas

📚 Guías de Desarrollo

✅ Frontend Vue.js - Completo ✅ Testing .NET - Completo ✅ Onboarding - Completo ✅ Caddy Setup - Completo

🚧 En Desarrollo

🎯 Productos

🚧 Web Tenant - En proceso

📁 Proyectos

🚧 Api.XXXXX - Planificado 🚧 Vue.Inventory - Planificado 🚧 Web.Tenant - Planificado

📚 Guías Adicionales

🚧 Backend .NET - Planificado 🚧 Base de Datos - Planificado 🚧 DevOps y Deploy - Planificado

🎯 Próximas Prioridades

📁 Completar documentación de proyectos principales
📚 Expandir guías de desarrollo
- Patrones .NET
- Estrategias de base de datos con Dapper

📋 Template por Sección

📁 1. Productos

Propósito: Documentar capacidades de negocio de alto nivel que pueden abarcar múltiples proyectos técnicos

Elementos Requeridos: - 🎯 Propósito del producto: ¿Para qué existe este producto? -

⚡ Funcionalidades principales: ¿Qué capacidades ofrece? - 👥 Usuarios objetivo: ¿Quién lo usa? (agentes, clientes finales, administradores) - 📊 Estado actual: Activo, en desarrollo, mantenimiento, deprecated - 🏢 Contexto de negocio: ¿Cómo encaja en la operación general? - 🔗 Proyectos técnicos relacionados: Enlaces a los proyectos que lo implementan - 📈 Métricas clave: KPIs de negocio relevantes

📁 2. Proyectos

Propósito: Documentar cada repositorio/aplicación técnica individual

Elementos Requeridos: - 🔧 Propósito técnico: ¿Qué resuelve específicamente este

proyecto? - 💻 Tecnología principal: Framework, versión, lenguaje (.NET 4.8, .NET Core 8, Vue.js, etc.) - 📦 Tipo de proyecto: Web App, API, SPA, Microservicio, Librería - 🎯 Producto(s) al que pertenece: Enlaces a productos de negocio que soporta - 👨‍💻 Responsable/Experto: Persona de contacto principal y backup - 📊 Estado del proyecto: Activo, mantenimiento, legacy, migración pendiente - 📚 Repositorio: Link directo y branch principal

Elementos Requeridos: 1. 📋 Prerrequisitos del sistema Versiones requeridas, herramientas

base 2. 📥 Clonado e instalación powershell # Comandos específicos para el proyecto git clone [repo-url] cd [project-name] # Comandos de instalación específicos 3. 🌍 Variables de entorno Configuración necesaria por ambiente 4. 🗄️ Base de datos Scripts de setup, migraciones iniciales 5. ⚡ Comandos de desarrollo - Ejecución local - Build para diferentes ambientes - Testing - Debugging 6. 🌐 Puertos y URLs Configuraciones de desarrollo local 7. ✅ Verificación de setup Checklist para confirmar instalación correcta Verificación de setup** Checklist para confirmar instalación correcta

📁 3. Guía de Desarrollo

Propósito: Centralizar conocimiento técnico, estándares y procesos del equipo

🎨 Frontend Vue.js

📚 Getting Started: Setup, Quick Start, Conceptos Clave, 📋 Templates y Scaffolding: Generación automática de código y proyectos 💻 Desarrollo Día a Día: Workflows, composables, patrones comunes 🏗️ Arquitectura: Microfrontends, monorepo, comunicación entre componentes

🔧 Backend .NET

🧪 Testing .NET: Objetivos y Scope, Proceso Paso a Paso, Herramientas y Scripts ⚡ .NET Core 8: 🚧 Minimal APIs, Dependency Injection, Middleware 🎯 Patrones y Mejores Prácticas: 🚧 Clean Architecture, SOLID, Repository Pattern

🗄️ Bases de Datos

🖥️ SQL Server: 🚧 Configuración, optimización, mejores prácticas 📈 Migraciones: 🚧 Estrategias y procedimientos

🚀 DevOps y Deploy

⚡ Caddy Setup: Descripción General, Quick Start, Configuraciones, Troubleshooting ⚙️ CI/CD Pipelines: 🚧 Azure DevOps, deployment strategies 🌍 Environments: 🚧 Configuración de ambientes (Dev, QA, Staging, Prod) 📊 Monitoring: 🚧 Logging, métricas, alertas

📁 Procesos y Workflows

Día 1 - Contexto del Equipo, Día 2 - Setup del Entorno, Día 3 - Documentación, Guía de Documentación

📁 Procesos Comunes

Procedimientos estándar por ambiente

🔗 Navegación y Relaciones

🗺️ Mapeo de Dependencias

graph TD
    A[Web Tenant] --> B[Web.Tenant]
    A --> C[Api.XXXXXXX]
    A --> D[Vue.Inventory]

    E[Otro] --> F[AYA.Commission]

    G[Otro Producto] --> H[Api.NuevoProducto]
    G --> I[App.NuevoProducto]

    B --> J[/guia-desarrollo/frontend-vue/]
    B --> K[/guia-desarrollo/backend-net/]

    C --> L[/guia-desarrollo/backend-net/]
    D --> L

    subgraph "Documentación Implementada"
        J --> M[📋 Descripción General]
        J --> N[🚀 Quick Start]
        J --> O[🧠 Conceptos Clave]
        J --> P[🌳 Decision Tree]

        K --> Q[🛠️ Testing .NET]
        K --> R[⚙️ Setup Entorno]
    end

🔗 Enlaces Cruzados Requeridos

🎯 Productos ↔ 📁 Proyectos: Referencias bidireccionales claras
📁 Proyectos ↔ 📚 Guía de Desarrollo: Ejemplos específicos en guías
🛠️ Setup del Proyecto ↔ 🚀 DevOps: Procedimientos de deploy
🏗️ Arquitectura ↔ 🎯 Patrones: Links a mejores prácticas

✅ Checklist de Implementación

🎯 Para Productos

📄 Descripción de negocio clara y completa 2. ⚙️ Feature flags y configuraciones documentadas 3. 📋 Reglas de negocio principales identificadas 4. 🔗 Relación con proyectos técnicos establecida 5. 📈 Métricas de éxito definidas

📁 Para Proyectos

🛠️ Setup verificado paso a paso 2. ⚡ Comandos de desarrollo probados 3. 📦 Dependencias listadas y versionadas 4. 🏗️ Arquitectura diagramada 5. 👨‍💻 Experto técnico identificado 6. 📊 Estado de salud documentado

📚 Para Guía de Desarrollo

✅ Ejemplos funcionales y testeables 2. 📏 Estándares de código definidos 3. 👀 Procesos de review establecidos 4. 📋 Templates y scaffolding disponibles 5. 🚨 Troubleshooting common issues documentado

🔄 Mantenimiento y Evolución

👥 Responsabilidades

🎯 Productos

Product Owners + Tech Leads

📁 Proyectos

Desarrolladores asignados + Expertos técnicos

📚 Guía de Desarrollo

Arquitectos + Senior Developers

⏰ Ciclo de Actualización

Cambios en setup, comandos críticos

🎯 Validación de Calidad

📋 Checklist de Validación:

🔗 Validación de Enlaces
- Enlaces internos funcionan correctamente
- Referencias bidireccionales son consistentes
- Links en diagramas Mermaid apuntan a rutas correctas
📊 Actualidad del Contenido
- Estado de implementación refleja la realidad
- Comandos son funcionales y testeados
- Screenshots y ejemplos están actualizados
🗺️ Navegación Coherente
- Estructura del astro.config.mjs coincide con contenido
- Breadcrumbs y enlaces cruzados son lógicos
- Iconografía es consistente

🔄 Procesos de Calidad:

👀 Code Review incluye docs: Cambios técnicos requieren actualización de docs
🧪 Onboarding testing: Nuevos miembros prueban la documentación
🔄 Feedback loops: Métricas de uso y efectividad
📊 Auditoría mensual: Validación sistemática de enlaces y contenido

🖼️ Gestión de Imágenes y Assets

📁 Estructura de Imágenes

La organización de imágenes sigue la misma jerarquía de la documentación para mantener coherencia y facilitar el mantenimiento:

src/assets/images/
├── proyectos/
│   └── web-tenant/
│       ├── feature/
│       │   └── xxxxxxx/
│       │       ├── arquitectura/
│       │       ├── debugging/
│       │       └── testing/
│       ├── arquitectura/
│       └── setup/
├── productos/
│   └── web-tenant/
│       ├── arquitectura/
│       ├── modos-operacion/
│       └── look-and-feel/
└── guias-desarrollo/
    ├── frontend-vue/
    ├── caddy/
    └── testing/

🏷️ Convenciones de Nomenclatura

Formato estándar:

{seccion}-{subseccion}-{descripcion-corta}.{ext}

Ejemplos específicos:

analytics-ga4-event-structure.png
analytics-data-manager-constructor.png
analytics-datalayer-events-list.png
arquitectura-components-diagram.svg
debugging-console-output.png
setup-caddy-config.png
motor-reservacion-booking-flow.png

📋 Reglas de Organización

📍 Ubicación

Principio: Imágenes van en la carpeta correspondiente al contenido que ilustran

Arquitectura → /arquitectura/
Debugging → /debugging/
Setup → /setup/

🏷️ Nomenclatura

Formato: seccion-contexto-descripcion.ext

Usar kebab-case (guiones)
Nombres descriptivos pero concisos
Incluir contexto de la sección

📦 Tipos Preferidos

Formatos recomendados:

.png para screenshots y UI
.svg para diagramas y iconos
.jpg solo para fotos reales

🔄 Proceso de Migración de Imágenes

Cuando se encuentren imágenes en ubicaciones incorrectas:

📋 Identificar el contenido que ilustra la imagen
📁 Crear la estructura de carpetas apropiada
🚚 Mover y renombrar siguiendo convenciones
🔗 Actualizar referencias en archivos .mdx
✅ Verificar que las imágenes se muestran correctamente

✅ Checklist de Implementación de Imágenes

📁 Estructura de carpetas creada según jerarquía de documentación
🏷️ Nombres de archivos siguen convención establecida
🔗 Referencias actualizadas en archivos .mdx correspondientes
📊 Imágenes optimizadas para web (tamaño y calidad)
📝 Alt text descriptivo para accesibilidad