Plantilla de Engineering Handbook

Overview

Los equipos sin un handbook escrito reinventan su cultura con cada nueva contratacion. Decisiones que eran obvias para los fundadores se convierten en misterios para el decimo ingeniero. Un engineering handbook captura las reglas, normas y razonamientos que definen como tu equipo construye software. No es un reemplazo de la conversacion. Es la referencia que hace las conversaciones productivas en lugar de repetitivas.

When to Use

• For alternatives, see SLA Definition Template.

Usa esta plantilla cuando:

• Tu equipo de ingenieria esta creciendo mas alla del grupo fundador
• Los nuevos contratados siguen haciendo las mismas preguntas sobre proceso o cultura
• Necesitas alinear multiples equipos u oficinas en practicas compartidas
• Estas preparandote para una auditoria que requiere procesos de ingenieria documentados
• Las practicas del equipo han evolucionado y necesitan ser capturadas antes de que el conocimiento se pierda

Prerequisites

Antes de escribir el handbook:

• Identificar quien posee el mantenimiento (usualmente engineering manager o tech lead)
• Decidir donde vive el handbook (wiki, Notion, repo Git, sitio de docs interno)
• Recopilar input de todos los miembros actuales del equipo sobre practicas actuales
• Revisar documentacion existente y marcar lo que sigue siendo preciso
• Establecer expectativas: este es un documento vivo, no un proyecto unico

Solution

# Engineering Handbook: `<Nombre del Equipo/Empresa>`

> Ultima actualizacion: ______ | Responsable: ______ | Preguntas: #engineering-help

---

## 1. Nuestra Filosofia

### Mision
[Una oracion describiendo para que existe el equipo de ingenieria]

### Principios
1. **______** — [Explicacion y que significa en la practica]
2. **______** — [Explicacion]
3. **______** — [Explicacion]

### Lo Que Valoramos
| Valor | Como Se Ve | Como No Se Ve |
|-------|------------|---------------|
| Calidad | Escribir tests antes de entregar; corregir causas raiz | Entregar codigo sin testear; aplicar parches temporales |
| Velocidad | PRs pequenos; feedback rapido; remover bloqueos | Apresurarse; saltarse revision; construir sin planificar |
| Colaboracion | Pairing; compartir conocimiento; debate respetuoso | Silos; culpa; acaparar informacion |
| Ownership | Arreglar lo que rompes; monitorear lo que despliegas | "Lanzar codigo por encima del muro"; ignorar alertas |

---

## 2. Como Trabajamos

### Comunicacion
| Canal | Uso Para | Tiempo de Respuesta | Notas |
|-------|----------|---------------------|-------|
| Slack #engineering | Discusion general; preguntas rapidas | Mismo dia | Publico por defecto |
| Slack DMs | Temas privados o sensibles | Mismo dia | Usar con moderacion |
| Email | Comunicacion externa; anuncios formales | 24 horas | |
| GitHub PR comments | Discusion especifica de codigo | Durante revision | Mantener tecnico |
| Video call | Discusiones complejas; kickoffs; 1:1s | Programado | Grabar si otros lo necesitan |

### Reuniones
| Reunion | Frecuencia | Duracion | Requerido | Proposito |
|---------|-----------|----------|----------|-----------|
| Standup | Diaria | 15 min | Todos | Bloqueos y coordinacion |
| Sprint Planning | Semanal/Quincenal | 60 min | Todos | Comprometerse con trabajo proximo |
| Retro | Semanal/Quincenal | 45 min | Todos | Mejora de proceso |
| 1:1 | Semanal | 30 min | Manager + IC | Crecimiento y apoyo |
| Tech Talk | Mensual | 30 min | Voluntario | Compartir conocimiento |

### Horarios y Disponibilidad
- Horas centrales de colaboracion: ______ a ______ [zona horaria]
- Horas flexibles fuera del tiempo central
- Ingenieros de guardia deben estar disponibles dentro de 15 minutos durante turnos
- Bloques libres de reuniones para foco: ______ [cuando]

---

## 3. Flujo de Desarrollo

### Nuestro Proceso
1. **Tomar trabajo** — Auto-asignar de columna lista en [sistema de tickets]
2. **Crear rama** — Seguir estrategia de branching (ver doc de Git Strategy)
3. **Escribir codigo + tests** — Todo codigo debe tener tests; todos los tests deben pasar
4. **Abrir PR** — Llenar plantilla de PR; solicitar revision de [miembros del equipo]
5. **Atender feedback** — Discutir, iterar, resolver
6. **Mergear** — Solo despues de aprobacion + CI verde; merge usando [estrategia de merge]
7. **Desplegar** — Seguir checklist de despliegue; monitorear despues del release
8. **Verificar** — Confirmar en produccion; cerrar ticket

### Definicion de Terminado
- [ ] Codigo escrito y testeado localmente
- [ ] Tests unitarios agregados/actualizados con >80% de cobertura
- [ ] Tests de integracion pasan
- [ ] Codigo revisado y aprobado por [numero] ingeniero(s)
- [ ] Documentacion actualizada (docs de API, README, runbooks)
- [ ] Monitoreo y alertas agregados para nueva funcionalidad
- [ ] Desplegado a produccion
- [ ] Verificado funcionando en produccion
- [ ] Ticket cerrado con notas de resolucion

### Estandares de Code Review
- Revisar dentro de [plazo] de apertura del PR
- Aprobaciones requeridas de [numero] ingeniero(s) no-autor
- Revisar por: correccion, mantenibilidad, seguridad, rendimiento, cobertura de tests
- Nits: prefijar con "Nit:"; el autor decide si atender
- Bloqueadores: deben resolverse antes del merge
- Si no entiendes algo, pregunta — el silencio no es aprobacion

---

## 4. Estandares Tecnicos

### Lenguajes y Frameworks
| Capa | Primario | Alternativas Aprobadas | Deprecado |
|------|----------|----------------------|-----------|
| Backend | ______ | ______ | ______ |
| Frontend | ______ | ______ | ______ |
| Mobile | ______ | ______ | ______ |
| Base de Datos | ______ | ______ | ______ |
| Cache | ______ | ______ | ______ |
| Cola | ______ | ______ | ______ |

### Principios de Arquitectura
1. **______** — [Ejemplo y razonamiento]
2. **______** — [Ejemplo y razonamiento]
3. **______** — [Ejemplo y razonamiento]

### Requisitos de Seguridad
- Todos los servicios autentican y autorizan peticiones
- Secretos nunca commiteados a codigo; usar gestion de secretos
- Dependencias escaneadas por vulnerabilidades semanalmente
- Encriptacion en transito (TLS 1.2+) y en reposo para datos sensibles
- Revision de seguridad requerida para cambios de auth, pagos, y manejo de datos

### Estandares de Observabilidad
- Todos los servicios exportan metricas (RED: Rate, Errors, Duration)
- Todos los errores logueados con formato estructurado y correlation IDs
- Todos los servicios tienen endpoints de health check
- Alertas definidas antes de entregar nuevas capacidades
- Dashboards creados para cada servicio

---

## 5. Practicas Operacionales

### Guardia
- Rotacion: ______
- Entrega: Cada [frecuencia] usando plantilla de entrega
- Tiempo de respuesta: P1 = 15 min, P2 = 30 min, P3 = 2 horas
- Escalamiento: Despues de [tiempo] sin reconocimiento
- Compensacion: ______ [si aplica]

### Respuesta a Incidentes
1. Reconocer pagina dentro del SLA
2. Declarar incidente en #incidents con severidad
3. Formar canal de respuesta al incidente
4. Comunicar segun plantilla de comunicacion
5. Enfocarse en mitigacion antes de causa raiz
6. Documentar cronologia durante la respuesta
7. Programar postmortem dentro de 48 horas de resolucion

### Despliegue
- Despliegues ocurren [frecuencia/horario]
- Todos los cambios a produccion via CI/CD; sin cambios manuales en produccion
- Feature flags para cambios riesgosos
- Despliegues canary o blue-green para servicios criticos
- Procedimiento de rollback probado mensualmente

### Entornos
| Entorno | Proposito | Quien Puede Desplegar | Datos |
|---------|-----------|----------------------|-------|
| Local | Desarrollo | Todo ingeniero | Sinteticos |
| CI | Testing automatizado | Sistema CI | Sinteticos |
| Staging | Validacion pre-produccion | Todo ingeniero | Produccion anonimizada |
| Produccion | Trafico en vivo | Guardia + TL | Reales |

---

## 6. Crecimiento Profesional

### Niveles de Ingenieria
| Nivel | Alcance | Impacto | Ejemplo |
|-------|---------|---------|---------|
| E1 | Tarea | Individual | Implementa capacidades asignadas |
| E2 | Capacidad | Equipo | Lidera desarrollo de capacidad |
| E3 | Sistema | Equipo + Cross-team | Posee arquitectura de servicio |
| E4 | Dominio | Organizacion | Define direccion tecnica para dominio |
| E5 | Organizacion | Empresa | Influencia tecnologia a nivel empresa |

### Criterios de Promocion
- Desempena consistentemente al siguiente nivel por [plazo]
- Demuestra impacto a traves de ejemplos concretos
- Recibe feedback de pares fuerte
- Completa hitos del plan de crecimiento

### Aprendizaje y Desarrollo
- [presupuesto] por ano para conferencias, cursos, libros
- Tech talks y workshops internos
- Pair programming y mentorias
- Hack days trimestrales

---

## 7. Como Cambiar Este Handbook

Este handbook es mantenido por [responsable] y actualizado a traves de:
1. Proponer cambios via PR a [repo del handbook]
2. Discutir en #engineering o reunion de equipo
3. Mergear despues de consenso de [tech leads / todos los ingenieros]
4. Anunciar cambios en #engineering
5. Actualizar materiales de onboarding si afecta

## Changelog

| Fecha | Cambio | Autor |
|-------|--------|-------|
| ______ | Version inicial | ______ |

Explanation

El template de handbook organiza el conocimiento del equipo en cuatro areas: filosofia (por que existimos), flujo de trabajo (como construimos), estandares (que significa calidad), y operaciones (como mantenemos sistemas funcionando). Separar estas secciones previene el error comun de documentar solo procesos mientras se dejan implicitos la cultura y los estandares tecnicos. El changelog y proceso de cambio al final dejan claro que es un documento vivo que evoluciona con el equipo.

Variants

Contexto	Ajustes	Notas
Startup < 10 ingenieros	Mas corto; enfocarse en principios sobre proceso	Documentar demasiado temprano crea burocracia
Enterprise > 100 ingenieros	Agregar secciones de cumplimiento, matrices de aprobacion, interfaces cross-team	Puede necesitar handbooks separados a nivel de equipo y de org
Remoto-first	Agregar normas de comunicacion async, cobertura de zonas horarias, eventos sociales virtuales	La documentacion escrita es mas critica
Industria regulada	Agregar secciones de seguridad, auditoria, y cumplimiento explicitamente	Requisitos SOC2, HIPAA, o PCI

Lo que funciona

1. Empieza pequeno, expande gradualmente. Un handbook de 5 paginas que la gente lee gana a uno de 50 paginas que ignoran.
2. Hazlo buscable. Los nuevos contratados buscan respuestas especificas, no una narrativa.
3. Revisa trimestralmente. Handbooks desactualizados son peores que ninguno; crean confusion.
4. Incluye razonamiento, no solo reglas. “Hacemos X porque Y” crea entendimiento, no solo cumplimiento.
5. Enlaza, no dupliques. El handbook deberia referenciar docs especializados (runbooks, docs de API) en lugar de incluir todo.

Common Mistakes

1. Escribirlo una vez y olvidarlo. Los handbooks se pudren mas rapido que el codigo; programa revisiones.
2. Copiar el handbook de otra empresa. La cultura es especifica del contexto; las practicas de Netflix pueden destruir tu equipo.
3. Hacerlo demasiado largo. Si toma mas de 20 minutos leer lo esencial, es demasiado largo.
4. Saltarse el “por que”. Reglas sin razonamiento se sienten arbitrarias y se ignoran.
5. No hacerlo descubrible. Enterrado en un wiki que nadie consulta es como no existir.

Frequently Asked Questions

Como mantenemos el handbook actualizado?

Trata las actualizaciones del handbook como parte de cambios de proceso. Cuando un equipo decide cambiar una practica, la actualizacion del handbook es el paso final de esa decision, no una tarea separada. Asigna un responsable que revise trimestralmente. Usa el changelog para rastrear cuando se actualizaron secciones.

El handbook deberia ser publico o interno?

Los engineering handbooks pueden ser publicos y frecuentemente sirven como herramientas de reclutamiento (GitLab, Buffer, y Basecamp publican los suyos). Manten interno procedimientos de seguridad, informacion de contacto de guardia, y procedimientos de incidente. Publica filosofia, proceso, y estandares tecnicos externamente para atraer candidatos que se alineen con tu enfoque.

Que tan detallados deberian ser los estandares de codigo?

Cubre principios y no-negociables (seguridad, manejo de errores, requisitos de testing). Deja el formateo a herramientas automatizadas (Prettier, Black, gofmt). No documentes cada decision posible — enfocate en donde el equipo ha hecho elecciones intencionales que difieren de los defaults de la industria.

Deberiamos usar un wiki o un repo Git para el handbook?

Un repo Git te da historial de versiones, revisiones de pull request para cambios, y notificaciones de diff. Los wikis son mas faciles de editar pero carecen de flujos de revision. Si tu equipo ya usa PRs para codigo, un repo Git crea consistencia: los cambios del handbook pasan por el mismo proceso de revision que los cambios de codigo. Usa un wiki solo si no-ingenieros necesitan editar el handbook frecuentemente y un flujo de PR crearia friccion.

Como medimos si el handbook es util?

Rastrea con que frecuencia los nuevos contratados lo referencian durante onboarding. Pregunta en check-ins de 30 dias: “El handbook respondio tus preguntas?” Monitorea queries de busqueda si tu sitio de docs soporta analiticas. Si las mismas preguntas siguen apareciendo en Slack a pesar de estar documentadas, el handbook puede ser dificil de encontrar o la seccion relevante puede ser poco clara.