Mejores Prácticas de Documentación | GitScrum
Crea y mantiene documentación útil y actualizada. Construye hábitos de documentación que apoyan tu proceso de desarrollo con NoteVault de GitScrum.
4 min de lectura
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 │
│ │
│ │
│ ## 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 │ └─────────────────────────────────────────────────────────────┘
``