Hay una pregunta que mide la resiliencia de una organización mejor que cualquier auditoría: qué pasa si la persona que sabe cómo funciona esto no está disponible. Si la respuesta es esperar a que vuelva, el conocimiento técnico no es un activo de la empresa, es un riesgo operativo.
La documentación debería ser la respuesta a esa pregunta. Casi todos los equipos tienen alguna, pero casi ninguno se fía del todo de ella. Dentro de un número dedicado a cómo se opera de verdad la tecnología que ya está en producción, este artículo trata de qué merece la pena documentar, qué no, y cómo evitar que lo escrito muera a los tres meses.
Por qué la documentación muere a los tres meses
No muere porque nadie la escriba. Muere por tres razones muy repetidas. Se escribe como un esfuerzo puntual, después de un proyecto o antes de una auditoría, y no como parte del trabajo diario. Se guarda lejos de donde ocurre el cambio, en una wiki que nadie abre cuando toca la configuración. Y pretende cubrirlo todo, de modo que cada cambio de versión la desactualiza un poco más hasta que el equipo deja de fiarse.
A partir de ese momento es peor que no tenerla, porque da respuestas que ya no son verdad. Quien lee no sabe distinguir una página vigente de una caducada y, ante la duda, pregunta a la persona de siempre. El círculo se cierra: la documentación se consulta menos, se corrige menos y se desactualiza más. El equipo de Spotify describía justo este problema al presentar TechDocs: con la documentación repartida entre wikis, documentos compartidos y ficheros README, el lector no tiene forma de saber si lo que tiene delante está al día.
Qué documentar y qué no
El criterio es sencillo: se documenta lo que alguien va a necesitar bajo presión o cuando no esté disponible la persona que lo sabe. Todo lo demás compite por un tiempo de revisión que nadie tiene.
Lo que sí merece estar escrito
Lo primero son los runbooks cortos, escritos para un momento concreto: qué hacer cuando salta esta alerta, cómo se restaura este servicio, a quién se llama si ocurre esto. Después, los diagramas de dependencias, que responden a la pregunta que nadie sabe contestar con prisa: qué se rompe si esto se cae. Conviene escribir también el porqué de las decisiones de arquitectura, porque el qué se puede deducir del sistema, pero el motivo se pierde en cuanto cambia el equipo. Y debajo de todo, un inventario con responsable: qué existe y quién responde de ello. Es la base de lo demás, algo que ya planteábamos en el artículo sobre convergencia entre IT y OT.
Lo que no vale la pena documentar
Lo que sigue es lo que más tiempo consume y menos devuelve. Para cada caso hay una alternativa mejor que escribirlo a mano:
| Lo que no merece el esfuerzo | Qué conviene hacer en su lugar |
|---|---|
| Valores de configuración copiados a mano, que cambian más rápido de lo que nadie puede revisar | Si la infraestructura se define como código, esa referencia ya existe y es la única que nunca miente |
| Manuales que repiten la documentación oficial del producto | Enlazarla y escribir solo lo que es propio de vuestro entorno |
| Capturas de pantalla de interfaces, que caducan con la siguiente actualización | Describir la tarea en texto y dejar la captura solo cuando no haya otra forma de explicarla |
| Todo lo que nadie va a leer | Si no se te ocurre quién lo abrirá ni en qué situación, probablemente no hace falta |
Un runbook que se usa y el sitio donde vive
Anatomía de un runbook útil
Un runbook útil responde a una situación concreta y puede seguirlo, a las tres de la madrugada, alguien que no lo escribió. Desde el punto de vista de Diátaxis, el marco que ordena la documentación técnica en tutoriales, guías prácticas, referencia y explicación, un runbook es una guía práctica: ayuda a completar una tarea concreta y no pretende enseñar ni justificar. Esa distinción importa, porque muchos manuales que nadie abre mezclan los cuatro tipos en el mismo documento. Un runbook que funciona suele tener esta estructura:
- Cuándo se usa: la alerta o el síntoma que lo dispara.
- Qué comprobar primero para confirmar que es esto y no otra cosa.
- Pasos en orden, con los comandos exactos y el resultado que se espera tras cada uno.
- Cómo saber que ha funcionado, para no dar por cerrado lo que sigue roto.
- Cuándo escalar y a quién, con una vía de contacto real.
- Propietario y fecha de la última revisión.
El último punto es el que más se olvida y el que más pesa, porque es lo que permite a quien lee decidir si fiarse. Un buen primer candidato es el orden de arranque de los servicios críticos y sus dependencias ocultas, justo lo que se descubre tarde cuando se prueba de verdad la recuperación de un backup: ahí un diagrama de dependencias y un runbook de arranque valen más que cualquier manual.
Dónde vive lo escrito
Cerca del cambio. Cuando la documentación se escribe en Markdown, se guarda en el mismo repositorio que el código y se publica de forma automática, se actualiza en el mismo movimiento en que se modifica el sistema. Es la idea de documentación como código que TechDocs aplica en Backstage: los documentos se construyen con MkDocs durante la integración continua y se acompañan de metadatos como el equipo propietario y la fecha de la última actualización, para que quien lee pueda juzgar si fiarse.
La herramienta depende del tamaño del equipo. Backstage compensa cuando hay muchos equipos y servicios y un catálogo central tiene sentido. Para un equipo pequeño, MkDocs por sí solo suele bastar para generar un sitio de documentación desde ficheros Markdown, sin montar una plataforma. Pero ninguna de las dos resuelve el problema por sí sola. Lo que lo resuelve es una costumbre: revisar el runbook afectado en la misma petición de cambio que modifica el sistema.
Por dónde empezar sin montar un proyecto de seis meses
Lo más razonable es elegir los tres servicios cuya caída más duele y dibujar para cada uno un diagrama de dependencias de una sola página. El siguiente paso es partir de los incidentes recientes. Un postmortem sin culpables bien hecho termina en acciones concretas y priorizadas, como recoge el capítulo sobre cultura de postmortem del libro de SRE de Google, y entre ellas a menudo hay un procedimiento que nadie tenía escrito. Ese es el primer runbook.
Después llega la prueba que más enseña: pedir a alguien ajeno al servicio que ejecute el runbook. Donde se atasque hay un hueco, y ese hueco es exactamente lo que se perdería el día que falte la persona de siempre. Para que lo escrito no vuelva a caducar, cada documento necesita un propietario y una fecha de revisión, y la revisión debe formar parte del cambio y no una tarea aparte que siempre se aplaza. Lo que nadie reclama, se archiva.
Documentar bien tiene además una lectura regulatoria. Como explicábamos en el artículo sobre NIS2 en España, la diferencia entre hacerlo bien y poder demostrarlo está en las evidencias, y unos procedimientos que existen, se usan y tienen fecha de revisión son evidencia de continuidad mucho más creíble que un manual extenso de hace dos años.
Documentar menos, y mejor situado
La documentación no es un entregable que se cierra, es parte de la operación. Se mide por lo que se usa, no por lo que ocupa. Y funciona bastante mejor cuando es corta, tiene dueño y vive junto a lo que describe que cuando se escribe entera una sola vez.
Si en tu organización este conocimiento sigue dependiendo de una o dos personas, el equipo de infraestructuras cloud y servicios IT de Irontec trabaja en la operación de clústeres con observabilidad, en DevOps e infraestructura como código y en la modernización del CPD con Proxmox. Y para quien prefiera delegar la operación, Linube ofrece administración de sistemas 24×7. El siguiente paso del número es qué hacer cuando suena el teléfono a deshoras, que es de lo que trata la guardia.
