Una buena documentación es un multiplicador de ingeniería por 10

El enfoque estándar de la documentación es que ayuda a la persona que la lee: el nuevo empleado, el ingeniero junior, el colega que trabaja en una parte desconocida del código base. Esto es cierto, pero infravalora drásticamente el beneficio al centrarse en el lado equivocado de la ecuación.

El beneficio mucho mayor es para las personas que dejan de ser interrumpidas.

El coste de la interrupción

Un ingeniero sénior que trabaja en un problema complejo necesita una concentración constante. Las investigaciones sobre el cambio de contexto muestran sistemáticamente que una interrupción, incluso breve, cuesta mucho más que la duración de la propia interrupción. El trabajo de Gloria Mark sitúa el tiempo de recuperación en unos 25 minutos para volver al mismo nivel de concentración tras una interrupción.

Un ingeniero sénior que es interrumpido diez veces al día por preguntas que se responderían con una buena documentación no solo pierde los diez minutos de respuesta, sino unas cuatro horas de enfoque productivo debido al coste de recuperación. Eso es la mitad de la jornada laboral consumida por la ausencia de documentos, y el ingeniero a menudo no reconoce lo que está sucediendo porque cada interrupción individual parece pequeña y manejable.

Las preguntas en sí son totalmente razonables. "¿Por qué el servicio de autenticación está estructurado de esta manera?" "¿Dónde encuentro la guía de despliegue?" "¿Cuál fue la razón para usar esta cola en lugar de una base de datos?" "¿Cómo maneja el flujo de datos los registros fallidos?" Cada una de estas preguntas tiene una respuesta, y en un equipo sin documentación, la respuesta vive en la cabeza de un ingeniero sénior y solo se puede acceder a ella interrumpiéndolo.

El efecto multiplicación

La buena documentación crea un efecto multiplicador que crece con el tamaño del equipo.

In un equipo de cinco personas, las interrupciones son manejables porque el equipo es pequeño y el contexto se comparte. En un equipo de veinte personas con cinco ingenieros sénior y quince personas que necesitan regularmente el contexto de estos, la carga de interrupción aumenta de forma no lineal. Cada ingeniero sénior es ahora un cuello de botella para las preguntas de tres o cuatro personas, y el coste agregado para la productividad de los ingenieros sénior es sustancial.

La documentación rompe este cuello de botella al hacer que el conocimiento de los ingenieros sénior esté disponible sin requerir su atención. El ingeniero junior lee el documento de arquitectura en lugar de preguntar. El nuevo empleado sigue la guía de incorporación en lugar de solicitar una explicación guiada. El colega que trabaja en un área desconocida del código base lee el registro de decisiones en lugar de programar una reunión.

Cada pregunta redirigida de una persona a un documento ahorra el tiempo de espera del que pregunta y el coste de interrupción de quien responde. Con diez preguntas al día en todo el equipo, el ahorro es de dos a cuatro horas de tiempo de ingeniería sénior, lo que equivale a tener un ingeniero sénior adicional cuya única contribución es responder preguntas por delegación.

Quién se beneficia más

Las personas que más se benefician de una buena documentación suelen ser los ingenieros más experimentados y valiosos del equipo, aquellos cuyo tiempo es más costoso y cuya concentración es más crítica. Estas son las mismas personas que soportan la mayor carga de documentación cuando los documentos se crean manualmente, lo que genera una dinámica especialmente ineficiente: las personas cuyo enfoque es más valioso son las que son interrumpidas con mayor frecuencia, y la solución (escribir documentación) también recae sobre ellas, consumiendo más de la concentración que se supone que debe proteger.

La documentación que se escribe sola rompe este ciclo al generar documentos a partir del trabajo existente del ingeniero sénior (sus descripciones de PR, sus explicaciones en Slack, sus contribuciones en reuniones) sin requerir trabajo adicional por su parte. El conocimiento que ya comparten de manera específica en cada contexto se captura y estructura para que cualquiera pueda encontrarlo, en cualquier momento, sin interrumpir a su fuente.

Preguntas frecuentes

¿Cómo medimos el coste de la interrupción? Realice un seguimiento del número de preguntas que reciben los ingenieros sénior a través de mensajes directos de Slack y solicitudes en persona durante una semana. Multiplique por 25 minutos (el coste promedio de recuperación por interrupción) para obtener el tiempo total de concentración perdido. La mayoría de los equipos descubren que la cifra es mucho más alta de lo que suponían.

¿No ocurrirá que los ingenieros junior simplemente no leerán la documentación? Si los documentos están actualizados, bien organizados y se pueden buscar, la adopción suele ser alta porque la alternativa (esperar a que responda un ingeniero sénior) es más lenta. Si la documentación está desactualizada y no es confiable, los ingenieros no la leerán de todos modos. La calidad de la documentación determina su adopción.

¿Justifica esto el coste de una herramienta de documentación? Con los salarios de los ingenieros sénior, recuperar incluso dos horas de concentración a la semana en un equipo pequeño suele superar el coste de cualquier herramienta de documentación del mercado. El cálculo del ROI casi siempre es positivo y el beneficio crece con el tamaño del equipo.

Lectura relacionada: Por qué es importante la documentación de ingeniería, El coste de escribir documentación de ingeniería, El coste oculto del conocimiento tribal. Páginas relacionadas: Documentación que se escribe sola, Para equipos de ingeniería.