Una automatización que solo una persona entiende es un punto único de fallo disfrazado de victoria de productividad. Funciona bien justo hasta que esa persona está de vacaciones, cambia de puesto, o deja el negocio, momento en el que un proceso que nadie más puede tocar con seguridad se rompe en silencio o se abandona por completo en vez de arreglarse. Ambos desenlaces cuestan más que la documentación habría costado, y por eso tratarla como opcional rara vez se sostiene en la práctica.
Lo que necesita de verdad la documentación, más allá de una descripción vaga
Un resumen de una línea de lo que hace la automatización no es documentación, es un título. Una documentación útil cubre el disparador que la inicia, cada paso principal en lenguaje sencillo, qué pasa cuando algo sale mal en cada uno de esos pasos, y dónde mirar cuando claramente no está funcionando como se espera. Esto no necesita ser un detalle técnico exhaustivo línea a línea, necesita ser suficiente para que alguien que no conoce la construcción concreta entienda su lógica y pueda hacer con seguridad un cambio pequeño.
Las capturas de pantalla envejecen mal, la lógica en lenguaje sencillo no
Una captura de pantalla de la interfaz de una herramienta concreta se queda desactualizada en el momento en que esa interfaz se rediseña, algo que ocurre con regularidad en la mayoría de plataformas. Describir la lógica de fondo en lenguaje sencillo, cuando pasa X, revisa Y, luego haz Z, sobrevive a un rediseño de plataforma de una forma que un tutorial lleno de capturas no lo hace, aunque las capturas se sientan más útiles de inmediato cuando se escriben.
Documenta las excepciones, no solo el camino feliz
El flujo principal de una automatización suele ser la parte más fácil de entender solo con abrirla y leer los pasos. Lo que es genuinamente difícil de reconstruir después es por qué una excepción concreta se maneja de la forma en que se maneja, por qué se salta cierto tipo de registro, por qué una condición particular dispara una revisión manual en vez de continuar automáticamente. Ese razonamiento vive en la cabeza de quien lo construyó a menos que se escriba explícitamente.
Mantén la documentación junto a la automatización, no en una wiki aparte
La documentación guardada en algún sitio desconectado de la automatización real tiende a desincronizarse a medida que la automatización se ajusta con el tiempo, porque actualizar una página de wiki lejana es un paso fácil de saltarse bajo presión de tiempo. Un campo de descripción breve dentro de la propia plataforma de automatización, o un documento enlazado directamente desde la herramienta, se mantiene conectado a lo que describe de una forma que un sistema separado a menudo no consigue.
Una plantilla mínima que cubre lo esencial
- Qué dispara esta automatización, y qué condiciones tienen que cumplirse para que se ejecute
- Los pasos principales, descritos en lenguaje sencillo en vez de jerga técnica específica de la herramienta
- Excepciones conocidas y cómo se maneja cada una actualmente
- A quién contactar y dónde mirar primero si algo parece roto
Esto lleva quizá veinte minutos escribirlo para una automatización moderadamente compleja, y son veinte minutos que se amortizan la primera vez que alguien distinto de quien la construyó necesita solucionar un problema, que es exactamente el escenario para el que debería planificarse desde el principio cada proyecto de automatización bien construido, no tratarse como un caso extremo improbable. Los equipos que se saltan este paso casi siempre lo lamentan en el momento menos oportuno posible, normalmente cuando quien lo construyó no está disponible.