Tu base de código está documentada. Tus decisiones no.

La mayoría de los equipos de ingeniería que funcionan bien disponen de una documentación de código razonable: comentarios, archivos README, documentación de API, firmas de tipos y docstrings. El propio código sirve como una forma de documentación de lo que hace el sistema. Un ingeniero competente que lea la base de código puede comprender el comportamiento actual de cualquier componente.

Lo que no pueden entender únicamente a partir del código es el porqué.

¿Por qué el servicio de autenticación es un microservicio independiente en lugar de un módulo en el monolito? ¿Por qué la canalización de datos utiliza el procesamiento por lotes en lugar de la transmisión en tiempo real? ¿Por qué se utiliza esta biblioteca en particular para las solicitudes HTTP cuando existe una alternativa más popular? ¿Por qué el esquema tiene una columna llamada legacy_status que se rellena pero nunca se lee?

Cada una de estas preguntas tiene una respuesta, y esa respuesta se debatió, discutió y decidió en algún momento del pasado. Probablemente la discusión tuvo lugar en un hilo de Slack, en una reunión o en un comentario de una solicitud de extracción (PR). Se tomó la decisión, se escribió el código y el razonamiento se evaporó.

El coste de perder las decisiones

Cuando se pierde el razonamiento detrás de una decisión, ocurren dos cosas.

Los nuevos ingenieros cometen errores que el equipo ya ha cometido antes. Un ingeniero que no sabe por qué el servicio de autenticación está separado del monolito podría proponer fusionarlos, pasar una semana creando una prueba de concepto y luego enterarse en una revisión de que la separación existe debido a un problema de latencia descubierto por las malas hace dos años. La semana se desperdició porque el razonamiento no estaba documentado.

Se vuelven a debatir decisiones ya resueltas. Alguien plantea la cuestión de procesamiento por lotes frente a transmisión en tiempo real para la canalización de datos. El equipo pasa una reunión debatiéndolo. A mitad de la reunión, alguien recuerda que esto ya se discutió hace un año y la conclusión fue que la transmisión en tiempo real requeriría cambios de infraestructura que no compensaban la mejora de la latencia. La reunión se desperdició porque la decisión anterior y su razonamiento no se podían encontrar.

Ambos costes son invisibles en el momento (parecen una discusión de ingeniería normal) y enormes en su conjunto (las mismas decisiones debatidas múltiples veces, los mismos errores repetidos por ingenieros sucesivos, el mismo contexto reconstruido desde cero cada vez que alguien nuevo se encuentra con el sistema).

Qué aspecto tiene la documentación de decisiones

Un documento de decisión no necesita ser elaborado. Los elementos esenciales son:

La pregunta. ¿Qué se estaba decidiendo? Planteada como una pregunta clara y fácil de buscar.

Las opciones consideradas. ¿Qué alternativas se discutieron? Incluso una lista breve es valiosa porque demuestra que se eligió el enfoque actual en lugar de adoptarse por defecto.

La decisión. ¿Qué se eligió?

El razonamiento. ¿Por qué se seleccionó esta opción? ¿Qué concesiones se aceptaron? ¿Qué tendría que cambiar para que se volviera a considerar la decisión?

La fecha y los participantes. ¿Cuándo se decidió esto y quién estuvo involucrado?

Este formato a veces se denomina Registro de Decisión de Arquitectura (ADR, por sus siglas en inglés), y los equipos que lo utilizan de manera constante informan de reducciones significativas en la reapertura de debates de decisiones y en la fricción durante la incorporación de nuevos miembros.

El aspecto de la automatización

El desafío de la documentación de decisiones es el mismo que con toda la documentación: requiere que alguien la escriba, y el momento de la decisión rara vez es el momento en el que a alguien le apetece escribir un documento sobre ella.

La documentación autoescrita puede capturar decisiones de las fuentes donde realmente se toman. Un hilo de Slack donde el equipo debate dos enfoques y llega a una conclusión se puede resumir automáticamente como un registro de decisión. Una reunión en la que se discuten opciones de arquitectura puede generar un documento estructurado a partir de la transcripción. La descripción de una PR que explica una elección de diseño no obvia se puede vincular al historial de decisiones más amplio.

Las decisiones ya se están tomando. Las discusiones ya están ocurriendo. Lo que falta es la captura, y la captura automatizada desde los canales existentes es mucho más confiable que pedirles a los ingenieros que redacten sus decisiones a posteriori.

Preguntas frecuentes

¿No es esto exagerado para decisiones pequeñas? No todas las decisiones necesitan un documento formal. El criterio límite: si esperarías que un nuevo ingeniero preguntara «¿por qué se hace esto así?» al encontrarse con ello, el razonamiento debería estar documentado. Las decisiones sobre arquitectura fundamental, elecciones tecnológicas y concesiones significativas casi siempre cumplen con este requisito.

¿Dónde deberían residir los documentos de decisión? Junto con la documentación del sistema, de manera que se puedan buscar y estén vinculados al código o sistema correspondiente. Un registro de decisiones separado de la wiki de ingeniería es mejor que nada, pero menos útil que tener las decisiones integradas con la documentación del sistema con la que se relacionan.

¿Cómo documentamos retroactivamente decisiones pasadas? Comience por las decisiones que causan más fricción: aquellas que se debaten de nuevo con más frecuencia o sobre las que los nuevos ingenieros preguntan más a menudo. Redacte el razonamiento a partir de las personas que lo recuerden y acepte que las decisiones más antiguas pueden tener que marcarse como «reconstruidas» en lugar de definitivas.

Lecturas relacionadas: El factor autobús, El coste oculto del conocimiento tribal, Deuda de documentación. Páginas relacionadas: Documentos autoescritos, Registro de decisiones, Para equipos de ingeniería.