3 min lectura • Guide 256 of 877
Mejores Prácticas de Documentación del Equipo
La documentación es o un activo o un pasivo. Buenos docs ayudan al onboarding, reducen preguntas, y preservan conocimiento. Docs malos—desactualizados, inencontrables, o incompletos—dañan activamente proveyendo información incorrecta.
Tipos de Documentación
| Tipo | Propósito | Frecuencia de Update |
|---|---|---|
| Architecture Decision Records | Por qué se tomaron decisiones | Cuando decisiones cambian |
| README | Cómo empezar | Con cambios mayores |
| Runbooks | Cómo manejar incidentes | Después de incidentes |
| API docs | Especificación de contrato | Con cambios de API |
| Process docs | Cómo trabaja el equipo | Review trimestral |
Qué Documentar
PRIORIDADES DE DOCUMENTACIÓN
════════════════════════════
MUST HAVE:
─────────────────────────────────────
1. GUÍA DE SETUP
"Cómo poner esto corriendo localmente"
├── Prerrequisitos
├── Clonar e instalar
├── Setup de ambiente
├── Correr localmente
├── Correr tests
├── Issues comunes
└── Guía de primera tarea
2. OVERVIEW DE ARQUITECTURA
"Cómo funciona este sistema"
├── Diagrama de alto nivel
├── Componentes y responsabilidades
├── Flujo de datos
├── Tecnologías clave
└── Dependencias externas
3. DECISIONES DE ARQUITECTURA (ADRs)
"Por qué elegimos este approach"
├── Contexto
├── Decisión
├── Consecuencias
└── Alternativas consideradas
4. PROCESOS DEL EQUIPO
"Cómo trabajamos juntos"
├── Workflow de desarrollo
├── Proceso de code review
├── Ceremonias de sprint
├── Rotación de on-call
└── Paths de escalación
5. RUNBOOKS
"Cómo manejar problemas"
├── Proceso de deploy
├── Procedimiento de rollback
├── Incidentes comunes
└── Contactos de emergencia
Manteniendo Docs Actualizados
ESTRATEGIAS DE ACTUALIZACIÓN
════════════════════════════
DOCS COMO CÓDIGO:
┌─────────────────────────────────────────────────────────────┐
│ │
│ • Docs viven en repo junto al código │
│ • Cambios de docs en mismo PR que cambios de código │
│ • Review de docs incluido en code review │
│ • CI puede verificar docs │
│ │
└─────────────────────────────────────────────────────────────┘
OWNERSHIP CLARO:
┌─────────────────────────────────────────────────────────────┐
│ │
│ • Cada doc tiene un owner │
│ • Owner responsable de mantener actualizado │
│ • Review scheduled (ej: trimestralmente) │
│ │
└─────────────────────────────────────────────────────────────┘
DEJAR MORIR DOCS OBSOLETOS:
┌─────────────────────────────────────────────────────────────┐
│ │
│ • Mejor sin doc que doc incorrecto │
│ • Archivar/borrar docs obsoletos │
│ • No acumular docs muertos │
│ │
└─────────────────────────────────────────────────────────────┘
En GitScrum
DOCUMENTACIÓN EN GITSCRUM
═════════════════════════
FEATURES:
┌─────────────────────────────────────────────────────────────┐
│ │
│ • NoteVault para documentación del equipo │
│ • Linking entre docs y tareas │
│ • Organización por proyecto │
│ • Search integrado │
│ │
└─────────────────────────────────────────────────────────────┘