Odoo · Documentación · Mantenimiento
Un módulo sin README es un módulo que solo entiende quien lo escribió, y ni siquiera él dentro de seis meses. En Odoo la documentación no es un lujo aparte: el propio manifest, la carpeta de módulo y los docstrings ya son una estructura pensada para documentar, si se usa bien.
__manifest__.py es el primer punto de documentación: summary, description y depends cuentan una historia.El primer contacto
El manifest ya es documentación, trátalo como tal
Un summary genérico ("Módulo de gestión") y una description vacía obligan a cualquiera a abrir el código para saber qué hace un módulo. Un manifest bien escrito responde en 10 segundos: qué problema resuelve, de qué depende y qué no incluye.
# __manifest__.py
{
"name": "Gestión de Incidencias de Flota",
"version": "19.0.1.0.0",
"summary": "Registra y da seguimiento a incidencias de vehículos de flota",
"description": """
Gestión de Incidencias de Flota
================================
Permite registrar incidencias (averías, siniestros, multas) asociadas
a vehículos de fleet.vehicle, con flujo de aprobación y notificación
al responsable de flota.
No incluye: gestión de talleres ni presupuestos de reparación.
""",
"depends": ["fleet", "mail"],
"category": "Fleet",
"license": "LGPL-3",
}description es lo que ve el usuario funcional al instalar el módulo desde Apps; el README es para quien va a tocar el código. Son audiencias distintas y ambos hacen falta.
Para quien mantiene el código
README técnico: decisiones, no solo instalación
Un README útil no repite lo que ya dice el manifest. Documenta las decisiones que no son obvias leyendo el código: por qué se eligió heredar en vez de delegar, qué modelos externos toca, y qué convención de nombres sigue el módulo. El objetivo es que alguien nuevo entienda el "por qué", no el "qué" (eso ya lo dice el código).
# README.md
## Gestión de Incidencias de Flota
### Decisiones de diseño
- Se hereda `fleet.vehicle` en vez de crear un modelo aparte porque
la incidencia necesita heredar las record rules de flota existentes.
- El estado usa `selection` simple, no un workflow con `state_machine`,
porque solo hay 3 transiciones posibles y no van a crecer.
### Convenciones
- Todos los modelos usan el prefijo `fleet_incident_*`.
- Las vistas heredan de `fleet.fleet_vehicle_view_form`, no crean formulario propio.Datos demo
Los datos demo documentan el caso de uso mejor que cualquier texto
Un fichero demo/demo_data.xml con 2-3 registros realistas (no "Test 1", "Test 2") deja ver de un vistazo cómo se usa el módulo en la práctica. Además sirve de humo: si los datos demo no cargan, algo en el módulo está roto antes de llegar a producción.
| Elemento | Qué debe contener |
|---|---|
summary | Una frase, para quien navega Apps |
description | Qué resuelve y qué NO incluye |
README.md | Decisiones de diseño y convenciones propias |
demo/*.xml | Casos de uso realistas, no placeholders |
| Docstrings en métodos complejos | El "por qué", nunca el "qué" (ya lo dice el nombre) |
Resumen
Documentar un módulo Odoo no exige herramientas nuevas: manifest, README y datos demo ya son la estructura prevista para ello. La clave es rellenarlos con las decisiones que no son obvias leyendo el código, no repetir lo que el propio código ya explica.