La deuda de documentación se acumula más rápido que la deuda técnica

Los ingenieros tienen una comprensión visceral de la deuda técnica. Saben lo que se siente al trabajar en una base de código donde se han acumulado atajos: cada uno de ellos era racional en su momento, pero el conjunto hace que todo sea más difícil. Saben que pagar la deuda técnica más adelante es más costoso que evitarla en primer lugar, y saben que ignorarla el tiempo suficiente eventualmente obliga a una reescritura.

La deuda de documentación funciona de la misma manera, con una diferencia importante: se acumula más rápido porque nadie la está rastreando.

La deuda técnica es al menos parcialmente visible en el propio código. Un desarrollador que lee un módulo desordenado puede sentir la deuda. Un revisor puede señalarla. Un linter puede detectar parte de ella. La deuda de documentación es invisible hasta que alguien necesita la documentación que falta y descubre que no está allí, momento en el cual el costo de crearla retroactivamente es mucho mayor de lo que habría sido el costo de crearla en primer lugar.

Cómo se acumula

Cada PR que se envía sin una actualización de documentación correspondiente añade un pequeño incremento de deuda de documentación. Cada decisión de arquitectura tomada en un hilo de Slack que nunca se plasma en un documento permanente añade más. Cada reunión donde se discuten prioridades y se comparte contexto verbalmente pero nunca se escribe añade aún más.

Individualmente, cada uno de estos parece insignificante. Colectivamente, a lo largo de los meses, crean una brecha entre lo que hace el sistema y lo que cualquiera que no sea de los desarrolladores originales entiende sobre él. La brecha crece con cada sprint y, debido a que es invisible (ninguna métrica la rastrea, ningún panel de control la muestra), crece sin que nadie lo note hasta que un evento desencadenante la hace dolorosamente evidente.

Los eventos desencadenantes son predecibles: un nuevo empleado que tarda meses en ser productivo, un ingeniero clave que se va y se lleva consigo un contexto crítico, un incidente de producción donde la respuesta es lenta porque nadie entiende el sistema afectado lo suficientemente bien como para diagnosticarlo rápidamente, o una revisión de arquitectura donde el equipo descubre que están volviendo a discutir decisiones que se tomaron y resolvieron hace un año.

Por qué se compone más rápido que la deuda técnica

La deuda técnica se acumula linealmente con los cambios de código. Cada atajo añade una unidad de deuda. La deuda de documentación se compone, porque el valor de la documentación es relacional: un documento sobre el Servicio A es más útil cuando se conecta con documentos sobre los Servicios B y C, y la falta de cualquiera de ellos reduce el valor de los demás.

Cuando falta la documentación de un sistema, la documentación de los sistemas que interactúan con él se vuelve menos útil, porque el lector no puede seguir las conexiones. Cuantos más sistemas estén indocumentados, menos valor proporciona cualquier documento individual, porque existe de forma aislada en lugar de como parte de un panorama conectado.

Esto significa que la deuda de documentación no es simplemente aditiva. Cada incremento de deuda hace que la documentación existente sea menos valiosa, lo que hace que el costo total de la deuda crezca más rápido que la tasa a la que se añade nueva deuda. Para cuando la deuda es lo suficientemente grande como para ser notoria, ya es más costoso pagarla de lo que la mayoría de los equipos están dispuestos a invertir, razón por la cual la respuesta común es aceptarla y trabajar en torno a ella en lugar de abordarla.

El punto de inflexión según el tamaño del equipo

La deuda de documentación es tolerable en equipos pequeños porque el conocimiento tribal sirve como sustituto: todos lo saben todo porque la tribu es lo suficientemente pequeña. El punto de inflexión suele situarse entre los diez y los veinte ingenieros, que es también el momento en que la mayoría de los equipos empiezan a contratar rápidamente, lo que a su vez es el punto en el que más necesitan documentación y menos tiempo tienen para crearla.

Este momento es desafortunado pero predecible. El momento en que el equipo empieza a crecer es el momento en que la documentación se vuelve esencial, y también es el momento en que el equipo existente está más saturado y es menos capaz de asumir el trabajo adicional de escribirla. La deuda de documentación que se acumuló durante los primeros días, cuando no importaba mucho, de repente se vuelve crítica, y pagarla requiere desviar tiempo de ingeniería del trabajo de características impulsado por la contratación que está fomentando el crecimiento.

Los equipos que gestionan bien esta transición suelen ser los que automatizan la documentación antes del punto de inflexión en lugar de después, de modo que los documentos crecen junto con el equipo en lugar de quedarse atrás.

Preguntas frecuentes

¿Cómo medimos la deuda de documentación? Métricas proxy: tiempo de incorporación de un nuevo ingeniero, número de preguntas en Slack que se responderían con los documentos existentes si existieran, frecuencia de decisiones vueltas a discutir y tiempo para resolver incidentes de producción en sistemas con documentación frente a sistemas sin ella. Ninguna de estas mide la deuda de documentación directamente, pero juntas indican su magnitud.

¿Deberíamos hacer un sprint de documentación? Un sprint de documentación amortiza la acumulación de pendientes, pero sin un cambio en cómo se crean los documentos de forma continua, la deuda se volverá a acumular inmediatamente. Piense en ello como declararse en quiebra: borra la cuenta nueva pero no cambia los hábitos de gasto. La solución estructural es una documentación que se genera a sí misma a partir de la actividad de ingeniería en curso.

¿Con qué tamaño de equipo se vuelve esto crítico? La mayoría de los equipos lo sienten entre los 10 y los 20 ingenieros, pero la deuda comienza a acumularse desde el primer día. El mejor momento para abordarla es antes de que la sienta, porque el costo de la prevención es una fracción del costo de la cura.

Lectura relacionada: Por qué es importante la documentación de ingeniería, Los documentos desactualizados son peores que la falta de documentos, La paradoja de la documentación. Páginas relacionadas: Documentos que se escriben solos, Para equipos de ingeniería.