Engineering Handbook
The internal source of truth for our software engineering team.
Por qué existe
Este handbook es la fuente de la verdad del equipo de software. Sirve para encontrar lo que no sabemos sin depender de preguntarle a la persona correcta en el momento correcto.
Buena parte del conocimiento que sostiene la operación no está escrito en ninguna parte: vive en la cabeza de una sola persona. Este documento existe para sacarlo de ahí.
Dónde está el foco
El handbook tiene cinco secciones, pero dos concentran la prioridad. Las otras tres las acompañan.
| Foco | Qué contiene | Para qué sirve |
|---|---|---|
| Conocimiento crítico | Contexto, decisiones, deuda técnica, riesgos, trampas conocidas | Se lee para entender por qué las cosas son como son |
| Runbooks | Procedimientos paso a paso, con comandos exactos | Se ejecutan para hacer el trabajo |
Son las dos formas en que se pierde el conocimiento cuando alguien sale.
Un runbook captura lo que esa persona hace: la secuencia exacta, en orden, con los comandos. Sin él, un procedimiento rutinario se vuelve un proyecto de investigación.
El conocimiento crítico captura lo que esa persona sabe: por qué se decidió así, qué está mal a propósito, qué rompe de forma no obvia. Sin eso, alguien va a "arreglar" algo que estaba bien, o a repetir un error que ya se cometió.
Lo demás —convenciones, procesos de equipo, estándares— se puede reconstruir observando el código y trabajando. Esto no.
Para quién es
- Equipo de software — lo usa a diario para trabajar y para operar lo que ya está en producción.
- Jefatura de área — para entender cómo funciona el equipo y qué depende de quién.
- Gerencia — para tener visibilidad de los riesgos y de cómo se sostiene la operación.
Qué deberías poder hacer después de leerlo
- Entender cómo está estructurado el equipo: quién hace qué y quién decide qué.
- Acceder al conocimiento crítico que hoy no está documentado: lo que solo una persona sabe.
- Ejecutar los procedimientos operativos siguiendo un runbook, sin haberlos hecho nunca antes.
- Operar y mantener los sistemas sin depender de una llamada.
Por dónde empezar
| Situación | Ir a |
|---|---|
| Tienes que ejecutar un procedimiento (dar de alta un cliente, aprovisionar infraestructura) | Runbooks |
| Quieres saber qué está mal y por qué sigue así | Deuda técnica y riesgos |
| Es tu primer día | Onboarding |
| Vas a trabajar con Git | Git workflow |
Estado actual
El handbook arranca deliberadamente pequeño: solo lo que ya tiene contenido real. Se irá complementando.
| Ya escrito | Estado |
|---|---|
| Runbook — Habilitar cuenta de m-system | Ejecutable, con puntos pendientes marcados |
| Deuda técnica y riesgos | 4 riesgos registrados |
| Mapa de sistemas | 9 aplicaciones y sus repositorios |
| Equipo | Estructura, composición y ownership |
Dentro de las páginas, lo que falta va marcado con un bloque Pendiente.
Eso es deliberado: una página que aparenta estar completa y no lo está es peor
que una vacía y honesta.
Mapa del handbook
- 01 · Equipo — quiénes somos y quién cuida qué.
- 02 · Sistemas — las aplicaciones y sus repositorios.
- 03 · Desarrollo — convenciones de trabajo.
- 04 · Runbooks — procedimientos ejecutables.
- 05 · Conocimiento crítico — deuda, riesgos y contactos.
- Plantilla de runbook — para escribir uno nuevo.
Cómo contribuir
Este sitio es Markdown versionado en Git. Se edita como código:
git switch -c docs/mi-cambio
# editar los .md dentro de docs/
npm start # preview en http://localhost:3000
git commit -am "docs: ..."
# abrir PR
Toda página tiene un enlace "Edit this page" al final que lleva al archivo correspondiente en el repositorio.
Mantenimiento
El handbook queda a cargo del equipo. Como referentes principales:
- Juan Carlos Sanguino — jefe de área.
- Andrés Rendón — líder de célula.
La frecuencia de revisión y el proceso de mantenimiento no están definidos: son decisión de quienes quedan a cargo.