6 min lectura • Guide 752 of 877
Gestión de Conocimiento para Equipos de Desarrollo
El conocimiento sale por la puerta cuando las personas se van. GitScrum ayuda a equipos a documentar decisiones, procesos y aprendizajes donde el trabajo sucede.
Tipos de Conocimiento
Qué Documentar
CATEGORÍAS DE DOCUMENTACIÓN:
┌─────────────────────────────────────────────────────────────┐
│ │
│ ARQUITECTURA & DISEÑO: │
│ • Diagramas de arquitectura del sistema │
│ • Documentación de API │
│ • Modelos de datos │
│ • Architecture Decision Records (ADRs) │
│ • Elecciones de tecnología y justificación │
│ │
│ PROCESOS: │
│ • Procedimientos de deployment │
│ • Runbooks de on-call │
│ • Guidelines de code review │
│ • Rituales de sprint │
│ • Respuesta a incidentes │
│ │
│ ONBOARDING: │
│ • Guías de setup │
│ • Normas y expectativas del equipo │
│ • Contactos clave y roles │
│ • Checklist de primera semana │
│ • Gotchas comunes │
│ │
│ DECISIONES: │
│ • Por qué elegimos X sobre Y │
│ • Contexto que informó decisiones │
│ • Trade-offs considerados │
│ • Cuándo revisar decisiones │
│ │
│ APRENDIZAJES: │
│ • Insights de post-mortem │
│ • Action items de retrospectivas │
│ • Conocimiento tribal │
│ • Tips y trucos │
└─────────────────────────────────────────────────────────────┘
Ubicación de Documentación
DÓNDE VIVE EL CONOCIMIENTO:
┌─────────────────────────────────────────────────────────────┐
│ │
│ EN REPOSITORIO DE CÓDIGO: │
│ │
│ /docs │
│ ├── README.md Quick start │
│ ├── CONTRIBUTING.md Cómo contribuir │
│ ├── architecture/ │
│ │ ├── overview.md Arquitectura del sistema │
│ │ └── decisions/ ADRs │
│ │ ├── 001-use-postgres.md │
│ │ └── 002-auth-approach.md │
│ ├── api/ Documentación de API │
│ └── runbooks/ Guías operacionales │
│ │
│ EN WIKI/NOTION: │
│ │
│ Team Handbook │
│ ├── Procesos del equipo │
│ ├── Calendarios de reuniones │
│ ├── Roles y responsabilidades │
│ └── Guía de onboarding │
│ │
│ EN GITSCRUM: │
│ │
│ • Contexto y requisitos de tareas │
│ • Historial de discusiones │
│ • Justificación de decisiones │
│ • Enlaces a docs relevantes │
│ │
│ PRINCIPIO: │
│ Docs técnicos → cerca del código │
│ Docs de proceso → wiki compartida │
│ Contexto de tarea → GitScrum │
└─────────────────────────────────────────────────────────────┘
Architecture Decision Records
Formato ADR
ARCHITECTURE DECISION RECORD:
┌─────────────────────────────────────────────────────────────┐
│ ADR-002: Usar PostgreSQL para Base de Datos Primaria │
├─────────────────────────────────────────────────────────────┤
│ │
│ STATUS: Aceptado │
│ FECHA: 2024-01-15 │
│ AUTORES: @alex, @maria │
│ │
│ ═══════════════════════════════════════════════════════════ │
│ │
│ CONTEXTO: │
│ Necesitamos una base de datos primaria para datos de │
│ usuarios, proyectos y tareas. Esperamos 100K usuarios │
│ en año uno, 1M para año tres. │
│ Equipo tiene experiencia con MySQL y PostgreSQL. │
│ │
│ DECISIÓN: │
│ Usaremos PostgreSQL como nuestra base de datos primaria. │
│ │
│ JUSTIFICACIÓN: │
│ • Mejor soporte JSON para schemas flexibles │
│ • Capacidades superiores de full-text search │
│ • Fuerte compliance ACID │
│ • Buen performance a nuestra escala esperada │
│ • Familiaridad del equipo │
│ │
│ ALTERNATIVAS CONSIDERADAS: │
│ │
│ MySQL: │
│ • Pro: Ligeramente más experiencia del equipo │
│ • Con: Soporte JSON más débil │
│ • Con: Necesita solución de búsqueda separada │
│ │
│ MongoDB: │
│ • Pro: Schema flexible │
│ • Con: Preocupaciones de eventual consistency │
│ • Con: Menos experiencia del equipo │
│ │
│ CONSECUENCIAS: │
│ • Necesitamos hosting PostgreSQL (RDS) │
│ • Capacitación del equipo en features específicas │
│ • Podemos aprovechar JSONB para campos extensibles │
│ │
│ FECHA DE REVIEW: 2025-01-15 (o a 500K usuarios) │
└─────────────────────────────────────────────────────────────┘
Cuándo Escribir ADRs
PUNTOS DE TRIGGER PARA ADR:
┌─────────────────────────────────────────────────────────────┐
│ │
│ ESCRIBE UN ADR CUANDO: │
│ │
│ ELECCIONES DE TECNOLOGÍA: │
│ • Seleccionar una base de datos │
│ • Elegir un framework │
│ • Adoptar un nuevo servicio │
│ • Escoger un vendor │
│ │
│ PATRONES ARQUITECTÓNICOS: │
│ • Microservices vs monolith │
│ • Approach de diseño de API │
│ • Estrategia de autenticación │
│ • Approach de caching │
│ │
│ CAMBIOS SIGNIFICATIVOS: │
│ • Reescribir un componente mayor │
│ • Cambiar estrategia de deployment │
│ • Modificar modelo de datos significativamente │
│ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ REGLA GENERAL: │
│ Si la decisión sería difícil de revertir o │
│ si impacta significativamente el sistema, │
│ documéntala en un ADR. │
│ │
│ FORMATO RÁPIDO: │
│ 1. Qué decidimos │
│ 2. Por qué lo decidimos │
│ 3. Qué más consideramos │
│ 4. Qué consecuencias tiene │
└─────────────────────────────────────────────────────────────┘
Mantener Docs Actualizados
MANTENIENDO DOCS FRESCOS:
┌─────────────────────────────────────────────────────────────┐
│ │
│ INTEGRAR EN FLUJO DE TRABAJO: │
│ │
│ Definition of Done incluye: │
│ ☐ Código completo │
│ ☐ Tests pasando │
│ ☐ Documentación actualizada (si aplica) │
│ │
│ OWNERSHIP: │
│ │
│ Documento │ Owner │ Frecuencia Review │
│────────────────────────┼──────────┼───────────────────────│
│ Arquitectura overview │ Tech Lead│ Trimestral │
│ Guía de onboarding │ EM │ Cada nuevo hire │
│ Runbooks │ SRE │ Después de incidente │
│ ADRs │ Autor │ Cuando aplica │
│ │
│ AUDITORÍA REGULAR: │
│ │
│ Trimestral: │
│ • Revisar docs de alto tráfico │
│ • Identificar contenido stale │
│ • Actualizar o archivar │
│ │
│ SEÑALES DE DOC STALE: │
│ • Menciona versiones antiguas │
│ • Referencias a personas que ya no están │
│ • Procedimientos que ya no funcionan │
│ • Screenshots desactualizados │
└─────────────────────────────────────────────────────────────┘
Mejores Prácticas
- Docs cerca del código para contenido técnico
- ADRs para decisiones significativas
- Integra en Definition of Done para mantenimiento
- Asigna owners a docs importantes
- Auditorías regulares para encontrar stale content
- Haz docs encontrables con buena estructura