📑 Instrucciones de Documentación del Proyecto¶
Este documento establece las pautas completas para generar, organizar y mantener la documentación técnica del proyecto dentro de la carpeta /docs, siguiendo las mejores prácticas de documentación de software y garantizando compatibilidad con MkDocs para la generación de sitios web de documentación.
🎯 Objetivo y Principios¶
Objetivo Principal¶
Crear documentación técnica basada en el código fuente actual que facilite: - El onboarding de nuevos desarrolladores al proyecto existente - La comprensión de la funcionalidad implementada - El mantenimiento y evolución del código actual - La referencia rápida de endpoints y configuraciones
Principios Fundamentales¶
- Basado en código: Toda documentación debe extraerse del código fuente actual
- Actualización: Documentación sincronizada con la implementación real
- Pragmatismo: Documentar lo que existe, no lo que se planea
- Simplicidad: Estructura mínima pero completa
- Utilidad: Información práctica para el desarrollo diario
📂 Estructura de la Carpeta /docs¶
La carpeta /docs debe organizarse en múltiples archivos Markdown especializados, con una estructura simple y enfocada en la documentación esencial del código actual:
/docs
├── index.md # Página principal e índice
├── introduccion.md # Descripción general del proyecto
├── configuracion.md # Setup y configuración del entorno
├── base_datos.md # Modelo de datos y BD
├── endpoints.md # Documentación de la API
├── flujos_funcionales.md # Procesos y casos de uso
├── casos_uso.md # Ejemplos prácticos
├── esquemas_diagramas.md # Diagramas del sistema
├── referencias.md # Enlaces y recursos
└── assets/
├── images/ # Imágenes y capturas
└── diagrams/ # Diagramas exportados
📄 Contenido Detallado por Archivo¶
🏠 index.md¶
# Documentación del Proyecto [Nombre]
## Navegación Rápida
- [Introducción](introduccion.md)
- [Configuración](configuracion.md)
- [Base de Datos](base_datos.md)
- [API](endpoints.md)
- [Flujos Funcionales](flujos_funcionales.md)
## Información del Proyecto
- **Versión**: X.Y.Z (basada en el código actual)
- **Última actualización**: YYYY-MM-DD
- **Stack principal**: Java + Spring Boot
- **Base de datos**: [Según el código actual]
## Enlaces Importantes
- [Repositorio](link)
- [Documentación API](endpoints.md)
🎯 introduccion.md¶
Basado en el código fuente actual: - Descripción del proyecto según el propósito actual - Stack tecnológico utilizado (extraído del pom.xml/build.gradle) - Módulos principales identificados en el código - Funcionalidades implementadas - Convenciones de desarrollo observadas en el código
🔧 configuracion.md¶
Derivado de la configuración actual:
## Requisitos del Sistema
[Basado en las dependencias del proyecto]
## Configuración Local
[Según archivos application.properties/yml existentes]
## Perfiles de Spring Boot
[Documentar perfiles existentes: dev, test, prod]
## Variables de Entorno
[Listar variables utilizadas en el código]
## Comandos de Ejecución
[Basado en la estructura del proyecto actual]
🗄️ base_datos.md¶
Extraído del código existente: - Entidades JPA encontradas en el código - Relaciones entre entidades - Scripts de inicialización (si existen en resources) - Configuración de conexión a BD - Migraciones Flyway/Liquibase (si están implementadas)
🌐 endpoints.md¶
Documentación generada desde los controladores existentes:
## Controladores Identificados
[Listar @RestController encontrados]
## Endpoints por Funcionalidad
### [Nombre del Controlador]
- **GET** /api/path - Descripción basada en el método
- **POST** /api/path - Descripción basada en el método
[Extraer de @RequestMapping, @GetMapping, etc.]
## Modelos de Request/Response
[Basado en DTOs y entidades del código]
📊 flujos_funcionales.md¶
Basado en la lógica de negocio implementada: - Servicios principales identificados - Flujos de datos entre capas - Procesos de negocio implementados - Diagramas de secuencia para flujos complejos
💡 casos_uso.md¶
Ejemplos extraídos del código actual: - Tests existentes como ejemplos de uso - Controladores y sus funcionalidades - Flujos end-to-end implementados - Datos de ejemplo basados en los tests
📈 esquemas_diagramas.md¶
Diagramas generados del código actual: - Diagrama de clases principales - Relaciones entre entidades - Flujo de datos entre servicios - Diagramas de la estructura de paquetes
📚 referencias.md¶
- Dependencias del proyecto (del archivo de build)
- Documentación de librerías utilizadas
- Enlaces a documentación oficial
- Changelog basado en commits recientes
🎨 Estándares de Formato y Estilo¶
Estructura de Documentos¶
# Título Principal (H1)
Descripción breve del documento y su propósito.
## Sección Principal (H2)
### Subsección (H3)
#### Detalle (H4)
**Texto en negrita** para conceptos importantes
*Texto en cursiva* para énfasis
`código inline` para comandos y variables
## Bloques de Código
```java
@RestController
public class UserController {
// Código ejemplo
}
Tablas¶
| Campo | Tipo | Descripción |
|---|---|---|
| id | UUID | Identificador único |
Listas¶
- Elemento 1
- Elemento 2
- Subelemento
### Convenciones de Naming - Archivos: `snake_case.md` - Carpetas: `snake_case` - Títulos: Sentence case - Variables: `UPPER_CASE` para constantes, `camelCase` para variables --- ## 📊 Diagramas y Recursos Visuales ### Tipos de Diagramas Recomendados 1. **Arquitectura**: C4 Model (Context, Container, Component, Code) 2. **Flujos**: Diagramas de secuencia y actividad 3. **Datos**: Diagramas ER y de clase 4. **Despliegue**: Diagramas de infraestructura ### Herramientas y Formatos - **Mermaid**: Para diagramas integrados en Markdown - **PlantUML**: Para diagramas complejos (exportar a PNG/SVG) - **Draw.io**: Para diagramas de arquitectura - **Lucidchart**: Para diagramas colaborativos ### Ejemplo Merm --- ## 🔧 Configuración MkDocs ### `mkdocs.yml` - Configuración Simplificada ```yaml site_name: Documentación [Nombre Proyecto] site_description: Documentación técnica del proyecto site_author: Equipo de Desarrollo # Repository repo_name: organization/project repo_url: https://github.com/organization/project edit_uri: edit/main/docs/ # Navigation nav: - Inicio: index.md - Introducción: introduccion.md - Configuración: configuracion.md - Base de Datos: base_datos.md - API/Endpoints: endpoints.md - Flujos Funcionales: flujos_funcionales.md - Casos de Uso: casos_uso.md - Esquemas y Diagramas: esquemas_diagramas.md - Referencias: referencias.md # Theme theme: name: material palette: - scheme: default primary: blue accent: blue toggle: icon: material/brightness-7 name: Switch to dark mode - scheme: slate primary: blue accent: blue toggle: icon: material/brightness-4 name: Switch to light mode features: - navigation.tabs - navigation.sections - navigation.top - search.highlight - search.share - content.code.copy # Extensions markdown_extensions: - admonition - pymdownx.details - pymdownx.superfences: custom_fences: - name: mermaid class: mermaid format: !!python/name:pymdownx.superfences.fence_code_format - pymdownx.highlight: anchor_linenums: true - pymdownx.inlinehilite - pymdownx.snippets - attr_list - tables - footnotes - toc: permalink: true # Plugins plugins: - search: lang: es - mermaid2 # Extra extra: social: - icon: fontawesome/brands/github link: https://github.com/organization/project extra_css: - assets/stylesheets/extra.css
Comandos MkDocs¶
# Instalar MkDocs y dependencias
pip install mkdocs-material mkdocs-mermaid2-plugin
# Servir documentación localmente
mkdocs serve
# Construir sitio estático
mkdocs build
# Desplegar a GitHub Pages
mkdocs gh-deploy
✅ Mejores Prácticas¶
Extracción desde Código¶
- Análisis del código fuente: Revisar estructura de paquetes, clases y métodos
- Configuración actual: Documentar archivos .properties/.yml existentes
- Dependencias reales: Extraer del pom.xml/build.gradle actual
- Tests como ejemplos: Usar tests unitarios/integración como casos de uso
- Comentarios del código: Aprovechar JavaDoc y comentarios existentes
Mantenimiento y Actualización¶
- Documentación como código: Versionar junto con el código fuente
- Revisión continua: Actualizar documentación en cada cambio significativo
- Validación: Verificar que ejemplos y configuraciones sean funcionales
- Sincronización: Mantener coherencia entre código y documentación
Calidad del Contenido¶
- Información verificable: Solo documentar lo que existe en el código
- Ejemplos reales: Usar datos y configuraciones del proyecto actual
- Enlaces funcionales: Referenciar archivos y clases existentes
- Contexto práctico: Explicar el propósito de cada componente implementado
Organización Simplificada¶
- Un archivo por tema: Separación clara de responsabilidades
- Navegación directa: Estructura plana sin subcarpetas complejas
- Índices claros: Enlaces directos desde el index.md
- Búsqueda eficiente: Organización que facilite encontrar información
Enfoque Práctico¶
- Configuración real: Pasos basados en la configuración actual
- Comandos funcionales: Solo incluir comandos que realmente funcionan
- Troubleshooting: Problemas conocidos del proyecto actual
- Quick start: Guía rápida para poner el proyecto en funcionamiento
🎯 Conclusión¶
Esta estructura de documentación simplificada garantiza: - Enfoque práctico: Documentación basada en código real existente - Mantenibilidad: Estructura simple y actualizable - Usabilidad: Navegación directa sin complejidad innecesaria - Relevancia: Información útil para el desarrollo diario - Coherencia: Sincronización entre código y documentación
El seguimiento de estas instrucciones resulta en documentación técnica práctica y útil que refleja fielmente el estado actual del proyecto y facilita el trabajo con el código existente.
Versión: 1.0
Fecha: 2025-08-12
Enfoque: Documentación basada en código actual