Infraestructura 2: Documentos de decisiones sobre la arquitectura

Un proyecto es, más que el código, el conjunto de decisiones que se han tomado de forma individual al crearlo o colectiva durante la fase de planificación. Estas decisiones se toman a todos los niveles: desde qué lenguaje usar, pasando por la decisión sobre una estructura de datos específica o sobre la modularización de una parte determinada del problema.

Registrar estas decisiones es imprescindible por dos razones

Onboarding, es decir, incorporación de nuevas personas al equipo.
Dar a personas que no hayan participado en una decisión conocimiento de la misma.
Registro de las decisiones para entender si se debe mantener la decisión en el futuro en caso de refactorización, o de que surja algún problema con la misma.

Y estas decisiones se tienen que registrar a todos los niveles. Principalmente a nivel de arquitectura, es decir, cómo se conectan entre sí los diferentes bloques de construcción de una aplicación, pero también a un nivel muy inferior donde se tomen decisiones con respecto a una herramienta determinada.

Dado que tienen un nivel muy diferente, la documentación sobre arquitectura puede ser bastante compleja; por eso hay plantillas que ayudan con esa decisión. No hay que ir por el camino más complicado, sin embargo; cualquier documento ADD (architecture design decision) debe tener, al menos, los diferentes apartados

Introducción y objetivos, es decir, por qué hay que tomar esa decisión
Restricciones: en muchos casos se estará condicionado por decisiones anteriores; una decisión sobre un lenguaje de programación o un servicio de almacenamiento de datos restringe las elecciones en el futuro.
Contexto y alcance: es decir, en qué contexto estamos, qué parte del sistema afecta, y hasta dónde alcanza. Si se va a decidir qué biblioteca de front-end se va a usar, no hay por qué decidir a la vez qué sistema de almacenamiento se va a usar. Hay que restringir todo lo posible el alcance de la misma; también qué hay que cambiar o construir una vez que se haya tomado la decisión.
Por qué se ha tomado esa decisión: ¿en qué requisitos se resume el contexto y las restricciones? ¿Qué métricas adecuadas a nuestro proyecto hemos elegido? ¿Nos importa más la madurez de una herramienta o sus prestaciones?
Es conveniente listar todas las opciones que se han considerado, todas las que cumplan los requisitos, y de qué forma son mejores o peores según los criterios elegidos (y sólo esos criterios).
Hay que explicar la decisión tomada, añadiendo cualquier otra información que sea relevante
Si tiene algún riesgo o se ha tomado la decisión sabiendo que genera deuda técnica, habrá que contarlo también a continuación.

A nivel de estructura de la documentación, habrá también que intentar que estos documentos se organicen jerárquicamente de forma que sea sencilla de encontrar la justificación de una decisión determinada.

El lugar donde se colocan estos documentos es en los sistemas de gestión de contenidos, casi siempre con estructura Wiki, que se usan: Confluence, por ejemplo, un producto de Atlassian, o el wiki que ofrece GitHub o GitLab.

Conviene que en este wiki, por ejemplo, se cree un apartado que se llame ADD y que también se numere cada decisión, de forma que sea sencillo referirse a ella.