Aunque puede sonar como la peor productora de discos de rock, los Architectural Decision Records (ADRs) son una técnica para documentar las decisiones técnicas y arquitectónicas en proyectos de software.
No es la primera vez que hablo de esto – los defiendo a ultranza como un knowledge asset que nos permite mantener el conocimiento sobre decisiones pasadas cerca de dónde se necesita, en un formato que nos facilita el registro y su lectura. Sobre todo, que captura lo raro en un documento: las alternativas y los porqué de una decisión.
¿Por qué es importante?
No hay proyecto de software que no sufra de «deuda de conocimiento«. Usualmente no se precisa que pase demasiado tiempo desde que tomamos una decisión relevante, para que frente a la pregunta «¿Por qué hicimos esto así?» se genere un silencio extraño, seguido de ruido que no responde de pleno la pregunta.
Esto podría no ser necesariamente un problema, pero lo es. Desde mi punto de vista, se manifiesta en las siguientes dimensiones:
Dificulta sumar ayuda
El onboarding de alguien se hace más largo y laborioso, con muchas instancias de conversación con dudas y preguntas. Se puede notar particularmente con colaboradores con más seniority, donde parte del valor agregado es «entrar corriendo» y se ven limitados cuando tratan de entender y acompañar decisiones previas.
Limita la adaptación
No podemos revisitar decisiones previas razonablemente, tratando de evaluar si estamos frente a un cambio de circunstancias o si es que perdimos de vista las contras de las alternativas. Así como es importante no cambiar caprichosamente, también es importante no ser necio ni caer en la falacia del pasto de al lado.
¿Sigue siendo el mismo contexto que cuando se tomó esta decisión? ¿Tenemos las mismas opciones a disposición? Son preguntas que deberíamos poder responder.
Dificulta el aprendizaje
Es importante entender si nos equivocamos en una decisión, y la mejor manera de hacerlo es evaluar si algo faltó al momento de tomarla. ¿Hubo contras que no previmos? ¿Obtuvimos efectivamente la ventaja que deseábamos?
Al no tener un registro claro de estas decisiones, se pierde el contexto y el razonamiento detrás de ellas.
¿Qué son los ADR?
Originalmente propuestos por Michael Nygard en su libro “Documenting Architecture Decisions”, los ADRs buscan registrar el contexto, las decisiones y las razones de manera que cualquier desarrollador pueda entender rápidamente el porqué de una determinada decisión.
Son una solución sencilla pero potente para mantener un rastro de esas decisiones sin generar un exceso de burocracia – a entender de varios, una de las razones de porqué muchas veces perdemos esta información.
Un ADR típico contiene cuatro componentes principales (distribuidos en diferentes formas):
- Contexto: ¿Cuál es el problema que se busca resolver? Incluye cualquier restricción relevante que influya en la decisión y la motivación.
- Decisión: ¿Qué se decidió? Hay que ser específico y conciso, describiendo la decisión tomada.
- Alternativas consideradas: ¿Qué otras opciones se discutieron? Esta sección es clave para mostrar el razonamiento y la comparación entre diferentes abordajes.
- Consecuencias: ¿Cuáles son los efectos de esta decisión? Aquí se mencionan tanto las ventajas buscadas como las desventajas que estamos dispuestos a aceptar a cambio.
Este formato proporciona un marco simple y flexible que permite capturar las decisiones manteniendo la documentación ligera para los equipos. Aunque parece una solución demasiado simple a un problema de peso, su potencia aparece cuando le damos un uso consistente para registrar las diferentes decisiones que nos encontramos.
¿Cómo lo aplico?
Hay varios recursos para empezar, pero lo más importante es comenzar de una vez e ir practicando. Para cada decisión de relevancia que amerite un ADR, hacemos una reunión rápida y acotada en el tiempo donde completamos el documento.
Las dos primeras seguramente son las que más cuestan, porque todos tienen que entender la dinámica y encontrar el ritmo para que no sea un ritual pesado. Luego comienza a tomar forma y volumen el registro de ADRs – y comienza a sentirse el valor de lo que se está construyendo.
¿Algún tip?
Identificá tus decision criteria
Durante la confección de un ADR deberían identificar y listar cuales son los criterios de decisión. ¿Qué cosas son importantes y estamos buscando? ¿Qué no lo es tanto? Esto ayuda a conducir la discusión y también tener una mirada objetiva sobre qué tanto se alinean los distintos pros y contras hacia los criterios establecidos.
El lugar y formato importan
Los ADR tienen que estar cerca del código idealmente. A veces es más prácticos no tenerlos en un repositorio (por ejemplo, si son varios) pero la colección debería estar referenciada desde el README al menos.
Tiene que haber un template uniforme definido, idealmente para toda la organización. Esto permite comenzar a documentar fácilmente y permite agarrar ritmo en forma consistente. Es importante no hacer el template pesado. ¡Atentamos contra el objetivo principal!
Si amerita una reunión, amerita un ADR
Mi heurística para saber si estamos frente a una decisión que amerita registrar un ADR, es si estamos frente a una reunión o call para decidir cómo hacer algo o qué herramienta usar – estamos frente a un ADR a registrar.
Que el instrumento guíe la discusión
Una reunión para decidir bien puede estructurarse como una conversación para ir completando casi secuencialmente el documento de ADRs. Aunque puede servir en otros casos no hacerlo así, cuando comenzamos a incorporarlos es una gran forma de mantener la conversación ordenada.
¿Dónde puedo encontrar más información?
En el Github de ADRs se encuentran referencias. En cuanto a artículos, el de 18F para mi hace un muy buen resumen del valor en esta práctica.
Juan Saavedra 