4 min lectura • Guide 640 of 877
Mejores Prácticas de Documentación
Buena documentación acelera el onboarding, reduce silos de conocimiento, y previene preguntas repetidas. Las características de documentación de GitScrum ayudan a los equipos a mantener documentación viva junto con su trabajo de desarrollo, asegurando que los docs se mantengan actuales y accesibles.
Estrategia de Documentación
Qué Documentar
PRIORIDADES DE DOCUMENTACIÓN:
┌─────────────────────────────────────────────────────────────┐
│ DEBE DOCUMENTAR: │
├─────────────────────────────────────────────────────────────┤
│ ✓ Getting started / Instrucciones de setup │
│ ✓ Vista general de arquitectura │
│ ✓ Documentación de API │
│ ✓ Opciones de configuración │
│ ✓ Procedimientos de deployment │
│ ✓ Runbooks de incidentes │
│ │
│ DEBERÍA DOCUMENTAR: │
├─────────────────────────────────────────────────────────────┤
│ ○ Architecture decision records (ADRs) │
│ ○ Pasos comunes de troubleshooting │
│ ○ Procesos y acuerdos del equipo │
│ ○ Checklist de onboarding │
│ │
│ CONSIDERA NO DOCUMENTAR: │
├─────────────────────────────────────────────────────────────┤
│ ✗ Código obvio (auto-documentado) │
│ ✗ Workarounds temporales (usar comentarios) │
│ ✗ Notas de reuniones (a menos que decisiones) │
└─────────────────────────────────────────────────────────────┘
Tipos de Documentación
ESTRUCTURA DE DOCUMENTACIÓN:
┌─────────────────────────────────────────────────────────────┐
│ TIPO │ AUDIENCIA │ PROPÓSITO │
├───────────────┼──────────────┼─────────────────────────────┤
│ README │ Nuevos devs │ Quick start, overview │
│ API Docs │ Consumidores │ Cómo usar el servicio │
│ Arquitectura │ Equipo │ Cómo funciona el sistema │
│ ADRs │ Equipo/Futuro│ Por qué se tomaron decisiones│
│ Runbooks │ Ops/On-call │ Cómo responder a issues │
│ Tutoriales │ Nuevos devs │ Aprendiendo el codebase │
│ Referencia │ Todos los devs│ Detalles técnicos completos│
└─────────────────────────────────────────────────────────────┘
Escribiendo Docs Efectivos
Template de README
ESTRUCTURA ESTÁNDAR DE README:
┌─────────────────────────────────────────────────────────────┐
│ # Nombre del Proyecto │
│ │
│ Descripción de una línea de lo que hace. │
│ │
│ ## Quick Start │
│ ```bash │
│ npm install && npm start │
│ ``` │
│ │
│ ## Prerrequisitos │
│ - Node.js 18+ │
│ - PostgreSQL 14+ │
│ │
│ ## Instalación │
│ Instrucciones de setup paso a paso │
│ │
│ ## Configuración │
│ Variables de entorno y opciones │
│ │
│ ## Desarrollo │
│ Cómo ejecutar localmente, tests, etc. │
│ │
│ ## Contribuir │
│ Cómo enviar cambios │
│ │
│ ## Licencia │
└─────────────────────────────────────────────────────────────┘
Architecture Decision Records
TEMPLATE DE ADR:
┌─────────────────────────────────────────────────────────────┐
│ # ADR-001: Usar PostgreSQL para base de datos principal │
│ │
│ ## Estado │
│ Aceptado │
│ │
│ ## Contexto │
│ Necesitamos una base de datos para datos de usuario. │
│ Requisitos: │
│ - Cumplimiento ACID │
│ - Soporte JSON │
│ - Familiaridad del equipo │
│ │
│ ## Decisión │
│ Usaremos PostgreSQL 14. │
│ │
│ ## Consecuencias │
│ - El equipo ya conoce PostgreSQL │
│ - Buen ecosistema de herramientas │
│ - Necesitaremos gestionar upgrades │
│ │
│ ## Alternativas Consideradas │
│ - MySQL: Menos soporte JSON │
│ - MongoDB: Equipo no familiarizado │
│ │
│ Fecha: 2024-01-15 │
└─────────────────────────────────────────────────────────────┘