Arquitecture Decision Records

Las elecciones de tecnolog铆a y soluciones propuestas para completar un projecto est谩n influenciadas por diversas decisiones tomadas por los miembros del equipo involucrados en el proyecto durante la fase de desarrollo. Las ADR ayudan a nuevos integrantes del equipo a comenzar m谩s r谩pido y a documentar los factores que jugaron un rol importante para llegar a una decisi贸n, dando contexto y respondiendo las preguntas 驴Qu茅?, 驴Por qu茅?, 驴C贸mo?, 驴Cu谩ndo? y 驴D贸nde? de cada decisi贸n ([cognitect-2011]). En la comunicaci贸n t茅cnica no se habla mucho sobre c贸mo se apoya las decisiones. En muchos casos se habla sobre apoyo a las tareas. La informaci贸n que las personas necesitan para completar las tareas no es unicamente la relativa a sobre c贸mo operar las m谩quinas o procesos, mas bien se necesita informaci贸n que apoye la toma de decisiones. Documentar los procesos no es suficiente, ya que es necesario documentar el contexto, permitiendo a los usuarios conocer las decisiones que deben tomar, sus consecuencias como tambi茅n recursos y referencias que ayudar谩n a determinar la decisi贸n a tomar ([baker-2013]).

Entre alguna de las ventajas de usar ADR se puede mencionar:

  • Ayudan a reducir el n煤mero de reuniones.

  • Permiten tener un acervo documental para tomar decisiones m谩s complejas.

  • Dan contexto y permiten analizar distintas opciones para encausar el proyecto al mejor camino de forma m谩s certera.

  • Permiten una conversaci贸n abierta a los integrantes del equipo y reducen el tiempo de explicaci贸n sobre las deciciones tomadas en un 谩rea.

Recomendaciones

  • Todas las decisiones importantes deben ser documentadas con ADR.

  • Los miembros del equipo deben aprender el formato para crear y leer ADR.

  • Las discuciones sobre los ADR deben ser realizadas en herramientas de colaboraci贸n que reduzcan los tiempos de reuniones al permitir que cada miembro pueda comentar as铆ncronamente.

  • Los miembros del equipo deben mantener actualizados los ADR cambiando su estado, datos y metadatos seg煤n la evoluci贸n hist贸rica de las decisiones.

  • Los ADR son escenciales para ver la evoluci贸n hist贸rica de un proyecto, como una central de todas las decisiones. Por lo que son vitales para planificar nuevas caracter铆sticas y evoluci贸n futura del proyecto.

  • Almacenarlos en un directorio llamado decisions (decisiones) dentro del c贸digo del proyecto con archivos en formato de texto plano como Asciidoc o dentro de un repositorio documental p煤blico y com煤n (antora, wiki, confluence).

Table 1. Tabla de Estados de un ADR
Estado Descripci贸n

Borrador (Draft)

El ADR todav铆a est谩 en preparaci贸n.

Propuesta (Proposed)

El ADR se ha creado y est谩 siendo discutido por los involucrados.

Aceptado (Accepted)

El ADR fue aceptado para su implementaci贸n.

Completado (Ready)

El ADR fue aceptado e implementado correctamente.

Obsoleto Suave (Soft Deprecated)

Un ADR completado ser谩 obsoleto. A煤n no existe un ADR completado alternativo.

Obsoleto Fuerte (Hard Deprecated)

Un ADR completado est谩 obsoleto y existe un ADR completado que lo reemplaza.

Cerrado (Declined)

El ADR no lleg贸 a una conclusi贸n definitiva en un tiempo determinado o no se completo lo suficiente para ser relevante en el contexto actual.

Plantilla

  • Estado: Borrador

  • Fecha Creaci贸n: 2024-03-22 (ISO 8601)

  • Fecha 脷ltima Modificaci贸n: 2024-03-22 (ISO 8601)

  • Participantes: (Quienes pueden opinar)

    • @Persona1

    • @Persona2

    • @Persona3

  • Decisores: (Quienes toman la decisi贸n)

    • @Persona4

    • @Persona5

    • @Persona6

  • Contexto

    • El contexto permite a los decidores realizar su an谩lisis y aplicar su juicio. Se recomienda dar la mayor cantidad de informaci贸n posible. Entre algunas cosas que puede llevar el contexto se encuentra: Breve descripci贸n de la situaci贸n actual, Diagramas de arquitectura, flujo, estado, secuencias, componentes, entre otros. 驴Cu谩l es el problema a resolver?, 驴Qu茅 factores claves pueden motivar la decisi贸n? (complejidad, riesgos, optimizaci贸n, calendarios y otras prioridades).

  • Lista de opciones y alternativas

    • Se presenta una lista de opciones y alternativas con sus respectivos an谩lisis (descripci贸n, diagramas, ventajas, desventajas, posibles consecuencias de su elecci贸n) que permitan elegir una decisi贸n final.

  • Decisi贸n

    • Se da una decisi贸n final por los involucrados considerando todos los factores y opciones presentados en el contexto y alternativas.

  • Observaciones y Notas

    • Se da apreciaciones sobre posibles problemas o consideraci贸n que podr铆an tener con la decisi贸n y los pasos a seguir para continuar con su implementaci贸n. Normalmente realizadas en el proceso de discuci贸n, se deben documentar en este segmento.

  • Preguntas Abiertas

    • Se da una lista de preguntas a tener en consideraci贸n y sus respuestas. Normalmente realizadas en el proceso de discuci贸n, se deben documentar en este segmento.