Skip to content

Templates de Documentación - AudioLab

Sistema de Templates para Documentación Consistente

🎯 Propósito

Este directorio contiene templates estándar para toda la documentación de AudioLab, garantizando consistencia y completitud en todo el proyecto.

📁 Estructura

03_INFRA/03_11_documentation_platform/_templates/
├── README.md                  # Este archivo
├── USAGE_GUIDE.md            # Guía paso a paso de uso
├── root/                      # Templates para carpetas raíz (XX_NOMBRE)
│   └── README.md.template
├── subsystem/                 # Templates para subsistemas (XX_YY_nombre)
│   └── README.md.template
└── component/                 # Templates para componentes (YY_ZZ_nombre)
    └── README.md.template

🚀 Uso Rápido

Crear Nuevo Sistema Raíz

# Ver guía completa de uso
cat 03_INFRA/03_11_documentation_platform/_templates/USAGE_GUIDE.md

# O manualmente copiar template
cp 03_INFRA/03_11_documentation_platform/_templates/root/README.md.template 21_NEW_SYSTEM/README.md

Crear Nuevo Subsistema

# Manual
cp 03_INFRA/03_11_documentation_platform/_templates/subsystem/README.md.template 04_CORE/04_16_new_subsystem/README.md
mkdir 04_CORE/04_16_new_subsystem/tests

Crear Nuevo Componente

cp 03_INFRA/03_11_documentation_platform/_templates/component/README.md.template 04_00_type_system/05_new_component/README.md

📝 Templates Disponibles

1. Root System Template

Para: Carpetas raíz (00-20) Incluye: - README.md completo - Estructura _docs/ completa - ARCHITECTURE.md básico - CHANGELOG.md

Campos a rellenar: - [SYSTEM_NAME] - [SYSTEM_NUMBER] - [BRIEF_DESCRIPTION] - [SUBSYSTEMS_LIST]

2. Subsystem Template

Para: Subsistemas dentro de sistemas raíz Incluye: - README.md con secciones estándar - Estructura tests/ - Guía de ejemplos

Campos a rellenar: - [SUBSYSTEM_NAME] - [SUBSYSTEM_NUMBER] - [PURPOSE] - [COMPONENTS_LIST]

3. Component Template

Para: Componentes individuales Incluye: - README.md mínimo - API documentation básica

Campos a rellenar: - [COMPONENT_NAME] - [API_DESCRIPTION] - [USAGE_EXAMPLE]

🔧 Personalización

Añadir Campos al Template

  1. Editar template base
  2. Usar sintaxis [FIELD_NAME]
  3. Documentar en README del template
  4. Actualizar script de generación

Crear Nuevo Template

  1. Crear directorio en _templates/
  2. Añadir README.md.template
  3. Documentar campos requeridos
  4. Actualizar este README

📊 Validación

Verificar que Template Funciona

# Crear instancia de prueba
.\scripts\create_from_template.ps1 -Type root -Name "_TEST_SYSTEM" -DryRun

# Validar estructura
.\scripts\validate_structure.ps1 _TEST_SYSTEM

Checklist de Template

  • Todos los campos [...] documentados
  • README.md compilable (Markdown válido)
  • Links internos funcionan
  • Ejemplos de código compilan
  • Estructura de directorios correcta

🎓 Mejores Prácticas

DO ✅

  1. Usar templates para TODO código nuevo
  2. Rellenar TODOS los campos - No dejar placeholders
  3. Personalizar ejemplos - No usar código genérico
  4. Validar antes de commitear - Run validate_structure.ps1

DON'T ❌

  1. No modificar templates sin RFC - Afecta a todo el proyecto
  2. No copiar docs antiguas - Usar templates frescos
  3. No skip secciones - Completar todo o marcar como N/A

📚 Referencias

🔄 Versionado de Templates

Version History

  • v1.0.0 (2024-10-16) - Templates iniciales basados en 04_CORE
  • v1.1.0 (TBD) - Refinamientos post-piloto
  • v2.0.0 (TBD) - Major revision basada en feedback

Updating Templates

Cuando actualices templates: 1. Increment version number 2. Document changes in CHANGELOG 3. Notify team 4. Update existing docs (optional but recommended)

📞 Soporte

Dudas sobre templates: 1. Consultar DOCUMENTATION_STANDARDS.md 2. Ver ejemplos en 04_CORE/ 3. Contactar Documentation Lead

Reportar problemas: - Template no funciona - Campo faltante - Mejora sugerida

Template System Version: 1.0.0 Last Updated: 2024-10-16 Maintained By: Lead Developer

Make documentation easy - use templates! 📝