Los documentos de ingeniería cuestan $50 000 al año. Nadie habla de ello.

Hay una partida en tu presupuesto de ingeniería que nadie tiene en cuenta: el tiempo que tus ingenieros pasan escribiendo y manteniendo la documentación. No aparece en ningún plan de proyecto, nunca se estima en la planificación del sprint y rara vez se discute en las retrospectivas. Pero es real, es caro y, para la mayoría de los equipos, es uno de los mayores costes no registrados del departamento.

Un ingeniero senior en EE. UU. que gana entre 180.000 y 220.000 dólares al año cuesta aproximadamente entre 85 y 105 dólares por hora si se incluyen los beneficios y los costes indirectos. Un ingeniero senior en el Reino Unido que gana entre 80.000 y 120.000 libras cuesta aproximadamente entre 50 y 75 libras por hora sobre la misma base.

Si ese ingeniero pasa cinco horas a la semana en tareas de documentación, escribiendo páginas wiki, actualizando documentos de arquitectura, documentando cambios en las API, explicando decisiones en texto largo en lugar de en código, el coste anual se sitúa entre 22.000 y 27.000 dólares en EE. UU. En un equipo de diez ingenieros que dedican cada uno de tres a dos horas a la semana a los documentos, el total es de 130.000 a 270.000 dólares al año en tiempo de ingeniería dedicado a escribir en lugar de construir.

Estas cifras son conservadoras. No incluyen el tiempo dedicado en Slack a explicar cosas que deberían estar en la documentación, el tiempo dedicado en reuniones a reconstruir un contexto que nunca se documentó, ni el tiempo dedicado a responder las mismas preguntas de incorporación cada vez que se incorpora un nuevo ingeniero.

Adónde va realmente el tiempo

Las cinco horas semanales no son un único bloque de redacción de documentación concentrada. Se reparten a lo largo de la semana en pequeños fragmentos, cada uno de los cuales conlleva su propio coste de cambio de contexto.

Documentación posterior a la solicitud de incorporación (PR). Después de enviar un cambio significativo, el ingeniero actualiza la wiki, la documentación de la API, el diagrama de arquitectura y cualquier archivo README relevante. Esto puede llevar de treinta minutos a una hora por cada PR importante, pero el cambio de contexto del código a la prosa es agotador de una manera que el tiempo por sí solo no refleja.

Responder a preguntas que deberían estar en la documentación. Un ingeniero junior pregunta por qué el servicio de pagos está estructurado de esa manera. Un gestor de producto pregunta cómo funciona el canal de datos. Una nueva incorporación pregunta dónde encontrar la guía de despliegue. Cada pregunta lleva de diez a veinte minutos, y las respuestas se dan verbalmente o en hilos de Slack donde se perderán en cuestión de días.

Mantenimiento de los documentos existentes. Una refactorización hace que tres páginas wiki dejen de ser precisas. Un cambio en la API invalida la guía de integración. Una actualización de dependencias rompe las instrucciones de configuración. Alguien tiene que buscar y solucionar esto, y el trabajo es tan tedioso que a menudo no se hace hasta que alguien sigue las instrucciones desactualizadas y pierde una tarde.

Documentación de incorporación. Cada nueva incorporación provoca un estallido de actividad de documentación cuando el equipo se da cuenta de que las cosas que han estado llevando en sus cabezas deben escribirse para alguien que no tiene el contexto. Esta es la documentación reactiva en su forma más costosa: creada bajo presión de tiempo, a menudo incompleta y rara vez mantenida después de que la nueva incorporación ya no la necesita.

El coste de oportunidad

El coste de la documentación no son solo las horas de salario. Es aquello para lo que se podrían haber utilizado esas horas en su lugar.

Cinco horas a la semana de tiempo de ingeniería senior son cinco horas de pensamiento arquitectónico, revisión de código, tutoría, depuración o trabajo en funcionalidades. A lo largo de un año, para un solo ingeniero, eso equivale aproximadamente a 250 horas, o unas seis semanas completas de trabajo, desviadas del trabajo para el que fue contratado.

Los ingenieros que sienten el coste de oportunidad de forma más aguda suelen ser los más experimentados, porque son los que tienen más contexto que documentar y los usos alternativos más valiosos para su tiempo. La carga de la documentación recae con mayor peso sobre las personas a las que la organización menos puede permitirse distraer.

La alternativa

El cálculo de costes anterior asume que la documentación requiere tiempo de ingeniería humana, lo cual ha sido cierto desde que existe la ingeniería de software. La documentación que se escribe sola cambia esta premisa.

Cuando la documentación se genera y se mantiene automáticamente a partir de la actividad de ingeniería que ya se está realizando, las fuentes que actualmente albergan tu conocimiento de forma transitoria (las PR y commits de GitHub, las conversaciones de Slack, las grabaciones de reuniones, los documentos de diseño), el coste de la escritura humana se reduce casi a cero.

Los ingenieros siguen revisando los documentos generados, corrigiendo imprecisiones y añadiendo el contexto que el sistema automatizado haya omitido. Pero el trabajo básico de convertir la actividad institucional en documentación estructurada y en la que se puedan realizar búsquedas lo gestiona el sistema en lugar de las personas cuyo tiempo cuesta entre 85 y 105 dólares por hora.

Para un equipo de diez ingenieros que dedican cada uno cinco horas a la semana a los documentos, eliminar incluso el 80% de ese esfuerzo manual ahorra entre 100.000 y 215.000 dólares al año en tiempo de ingeniería recuperado. Eso equivale a contratar a un ingeniero adicional, financiado en su totalidad por no desperdiciar el tiempo de los ingenieros que ya tienes.

Preguntas frecuentes

¿Es realista pensar en cinco horas a la semana? Las encuestas realizadas a equipos de ingeniería sitúan sistemáticamente el tiempo de documentación entre cuatro y ocho horas semanales para los ingenieros senior, y la cifra aumenta durante los periodos de incorporación y tras refactorizaciones importantes. Cinco horas es una estimación moderada, y muchos equipos descubrirían que su cifra real es mayor una vez que la registren.

¿Qué pasa con los equipos que simplemente no escriben documentos? Pagan el coste de otra manera: a través de tiempos de incorporación más largos, más interrupciones a los ingenieros senior, más errores debidos a una arquitectura mal entendida y una mayor pérdida de conocimiento cuando las personas se van. El coste de no escribir documentos suele ser mayor que el de escribirlos, solo que es menos visible porque se distribuye en decenas de pequeñas ineficiencias en lugar de aparecer como una sola partida presupuestaria.

¿Cómo calculas el coste para tu propio equipo? Cuenta el número de ingenieros, estima su promedio de horas semanales en actividades relacionadas con la documentación (escribir, mantener, responder preguntas que deberían estar en los documentos), multiplícalo por su coste por hora cargado. La mayoría de los equipos encuentran que la cifra es sorprendentemente grande una vez que realmente la calculan.

Lecturas relacionadas: Por qué es importante la documentación de ingeniería, Por qué los ingenieros odian escribir documentación, ¿Cuánto te está costando una mala documentación?. Páginas relacionadas: Documentación que se escribe sola, Para equipos de ingeniería.