La paradoja de la documentación: cada PR hace que tus documentos sean menos precisos

Este es el problema fundamental de la documentación de ingeniería: en el momento en que se escribe, empieza a dejar de ser cierta.

Una página de wiki describe con precisión la arquitectura del servicio de pagos el día en que se escribe. A la semana siguiente, una PR reestructura la lógica de reintentos. La semana posterior, otra PR añade la integración de un nuevo proveedor de pagos. Un mes después, una refactorización consolida dos módulos en uno solo. Ninguno de estos cambios actualiza la página de la wiki, porque no hay conexión entre el código y la documentación. Cada PR hace que la documentación sea ligeramente menos precisa, y el desfase se acelera a medida que aumenta la velocidad de entrega.

Esta es la paradoja de la documentación: cuanto más rápido entrega tu equipo, más rápido se queda obsoleta la documentación, lo que significa que los equipos que más necesitan una documentación fiable son aquellos cuya documentación se corrompe más rápidamente. La documentación manual es una carrera contra tu propia velocidad, y es una carrera que no puedes ganar porque la documentación siempre va un paso por detrás del código.

Por qué falla el mantenimiento manual

La respuesta habitual ante una documentación obsoleta es un proceso de mantenimiento: asignar responsables, programar ciclos de revisión, añadir actualizaciones de documentación a las listas de comprobación de las PR. Estos procesos ayudan en cierta medida, pero todos dependen de la disciplina humana, la cual se degrada precisamente bajo las condiciones en las que la documentación es más importante.

Cuando el equipo entrega a un ritmo rápido, bajo la presión de los plazos de entrega o lidiando con una incidencia, el mantenimiento de la documentación es lo primero que deja de ser prioritario. Los revisores de las PR dejan de comprobar si se ha actualizado la documentación. Los responsables de las páginas de la wiki se retrasan en su ciclo de revisión. El proceso de mantenimiento funciona cuando todo está tranquilo y falla cuando la situación se vuelve intensa, lo que significa que funciona menos cuando más se necesita.

El otro problema es que nadie sabe qué documentación se ve afectada por un cambio de código determinado. Una refactorización puede invalidar tres páginas de la wiki, dos diagramas de arquitectura y una guía de incorporación, y el ingeniero que realiza el cambio no tiene forma de saber qué documentos hacen referencia al componente que está modificando. Incluso un ingeniero concienzudo que desee actualizar la documentación no puede hacerlo de manera fiable porque la relación entre el código y la documentación no se mantiene y, a menudo, ni siquiera existe.

La solución arquitectónica

La única documentación que mantiene el ritmo de una base de código que evoluciona rápidamente es aquella que se actualiza a sí misma a partir de las mismas fuentes que modifican el código.

La documentación que se escribe sola resuelve la paradoja generando documentación a partir de la actividad de ingeniería en tiempo real. Cuando una PR cambia la forma en que se comunican dos servicios, la documentación sobre esa comunicación se actualiza para reflejar el cambio. Cuando una conversación de Slack debate y resuelve una cuestión de diseño, los documentos pertinentes incorporan la decisión. Cuando una reunión trata sobre un plan de migración, la documentación refleja el plan actual en lugar del de hace tres meses.

La documentación se mantiene al día porque se escribe a partir de las mismas fuentes que modifican el sistema. No hay brecha entre el código y la documentación porque esta se deriva de la actividad del código en lugar de mantenerse de forma paralela a él.

Los ingenieros siguen revisando y perfeccionando la documentación generada, pero la precisión básica se mantiene de forma automática, lo que significa que la revisión es un paso de control de calidad en lugar de un ejercicio de reescritura. La paradoja se resuelve porque la documentación no necesita sincronizarse manualmente con un objetivo en constante movimiento. Se mueve con él.

Preguntas frecuentes

¿Con qué rapidez se queda obsoleta la documentación que se mantiene manualmente? En equipos de ritmo rápido, pueden aparecer imprecisiones significativas a las pocas semanas de haberse escrito un documento. Un documento de tres meses de antigüedad en una base de código con desarrollo activo suele ser poco fiable en los detalles, aunque las líneas generales sigan siendo correctas.

¿Podemos simplemente marcar los documentos con una fecha de "última verificación"? Esto es mejor que nada porque da al lector una señal sobre cuánto confiar en el contenido. Pero no resuelve el problema subyacente: alguien tiene que seguir verificando el documento, y esa verificación requiere comprender qué cambios de código podrían haberlo invalidado.

¿Es este un problema para todos los tipos de documentación? Es peor para la documentación que describe detalles de implementación, arquitectura del sistema y puntos de integración, porque estos cambian con mayor frecuencia. La documentación conceptual (por qué utilizamos microservicios, nuestra filosofía sobre las pruebas) es más duradera porque las decisiones subyacentes cambian con menor frecuencia.

Lecturas relacionadas: La documentación obsoleta es peor que la falta de documentación, Deuda de documentación, Explicación de la documentación que se escribe sola. Páginas relacionadas: Documentación que se escribe sola, Para equipos de ingeniería.