Convenciones de Documentación

La documentación como código mantiene el conocimiento de la flota de Python descubrible: los ADRs explican el porqué, los runbooks explican los pasos de las 3 AM, las especificaciones explican qué se envía y los READMEs guían a los recién llegados, todo revisado en PRs como la lógica de la aplicación.

Receta

Tarjeta de receta de referencia rápida, lista para copiar y pegar.

docs/
  adr/0001-use-fastapi.md
  rfc/TEMPLATE.md
  runbooks/orders-api.md
  specs/2026-pdf-export.md
README.md          # enlaza a lo anterior

# Mínimo de README de servicio
- Propósito
- Desarrollo local (uv sync, pytest)
- Despliegue / reversión (enlazar runbook)
- Propietarios (@equipo, CODEOWNERS)
- Dashboards + guardia

Cuándo recurrir a esto:

• Arranque de nuevo servicio
• El guardia no encuentra el runbook
• Los ADRs en la wiki divergen de la realidad
• Solicitudes de auditoría cambian el historial

Ejemplo de Trabajo

# docs/adr/0002-celery-for-billing.md
 
## Estado
Aceptado
 
## Contexto
Los correos electrónicos y PDFs de facturación tardan entre 5 y 120 segundos; la API debe devolver 202 rápidamente.
 
## Decisión
Usar Celery con broker Redis; DLQ `billing_dlq`.
 
## Consecuencias
### Positivas
- Escalado independiente de los workers
### Negativas
- Operar Redis HA; monitorizar la profundidad de la cola
 
## Disparador de revisión
Cola sostenida >50k o necesidad de latencia sub-segundo

# docs/runbooks/orders-api.md (extracto)
 
## Reversión
kubectl rollout undo deployment/orders-api -n production
 
## Matar flag
CHECKOUT_MODE=checkout_v1
 
## Dashboards
- Grafana: Órdenes API SLO

Lo que esto demuestra:

• ADR usa secciones estándar y disparador de revisión
• Runbook tiene comandos ejecutables y claves de flag
• README apunta a rutas docs/ en el repositorio
• Todo el markdown revisado a través de PR

Inmersión Profunda

Cómo Funciona

• Única fuente de verdad - Rama principal de Git; la wiki es opcional.
• Plantillas - Plantillas de RFC, ADR, especificación, post-mortem en docs/.
• Higiene de enlaces - Enlaces relativos dentro del repositorio; verificación opcional de enlaces rotos en CI.
• Anotaciones de alertas - runbook_url apunta a markdown en la rama por defecto.
• Changelog - Notas de lanzamiento visibles para el cliente generadas a partir de etiquetas + enlaces a especificaciones.

Tipos de Documentos

Notas de Python

## Puntero a docstring de módulo
"""billing_tasks.py - ver docs/runbooks/orders-api.md#celery"""

Trampas Comunes

• Runbooks solo en wiki - Desviación de los comandos de producción. Solución: Repositorio canónico; la wiki importa o enlaza.
• ADRs nunca actualizados - Estado engañoso. Solución: Sustituir con un nuevo número de ADR.
• Especificaciones solo en tickets - Se pierden cuando Jira archiva. Solución: Copia de docs/specs/ en PR.
• README obsoleto - Nuevos empleados bloqueados desde el primer día. Solución: Cambio de README requerido en PRs relacionados con la incorporación.
• Enlaces relativos rotos - La confianza se erosiona. Solución: Verificador de enlaces opcional en CI en docs/.

Alternativas

Preguntas Frecuentes

Relacionado

• Registros de Decisiones de Arquitectura - Proceso ADR
• Directrices de Contribución - Documentos de PR
• Playbooks de Respuesta a Incidentes - contenido de runbook
• Requisitos a Especificaciones Técnicas - forma de especificación
• Estándares de Codificación y Guías de Estilo - documentación de código

Versiones de Stack: Esta página fue escrita para Python 3.14.0 (estable 3.14, mantenimiento 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, y uv 0.6+.