ADRs Registros de Decisiones Arquitectónicas Software Craftsman Solution Architect @ AVANADE GitKraken Ambassador Arquitectura de Soluciones Versión 1.0.0, Noviembre de 2024

2 2 Motivo de la elaboración de este documento (1/3) Aunque el proceso de asesoramiento arquitectónico transformará los procesos de toma de decisiones de tu organización, siempre lo combino con al menos un elemento adicional: los registros de decisiones arquitectónicas (ADR, por sus siglas en inglés). Son la mejor manera que conozco para mitigar las siguientes deficiencias de confianza derivadas del proceso de asesoramiento arquitectónico: Falta de confianza en tus habilidades y las de otros para tomar decisiones • Incertidumbre Natural: Asumir una nueva responsabilidad que requiere una habilidad poco utilizada genera incertidumbre en las personas. • Preocupación Dual: Existe una preocupación tanto por la propia capacidad para tomar decisiones acertadas como por la capacidad de los demás. • Percepción de Habilidad Innata: Los arquitectos veteranos parecen tener habilidades excepcionales, pero estas se desarrollan a través de años de práctica. • Reconocimiento de la Brecha de Habilidades: Es crucial reconocer la existencia de una brecha de habilidades y trabajar para fortalecerlas ampliamente. • Entorno de Apoyo: Un entorno de apoyo proporciona la confianza necesaria para practicar la toma de decisiones en situaciones cada vez más significativas.

3 3 Motivo de la elaboración de este documento (2/3) Falta de Confianza en la Búsqueda y Oferta de Asesoramiento • Transparencia en el Asesoramiento: Construir confianza es difícil cuando no se sabe quién participó en el asesoramiento, qué se aconsejó y si se comprendió correctamente. • Incertidumbre sobre la Experiencia: No hay forma de garantizar que las personas consultadas poseían la experiencia requerida o si sus contribuciones fueron desestimadas. • Mecanismo de Transparencia: Implementar un mecanismo que proporcione transparencia es esencial para que el proceso funcione correctamente y para construir confianza mutua. • Falta de Confianza en el Conocimiento Completo: La descentralización puede generar una falta de confianza en saber todo lo que está sucediendo en el proceso. Descentralización (consecuencias) • Cambio de Enfoque: En un enfoque tradicional, un grupo centralizado de arquitectos conocía todo lo que sucedía. En un enfoque descentralizado, no hay un grupo central que tome todas las decisiones. • Incremento de Decisiones: Al eliminar el cuello de botella de los enfoques tradicionales, se toman más decisiones. • Necesidad de Conocer el Contexto: Tanto los arquitectos como los equipos de desarrollo necesitan conocer el contexto en el que operan sus sistemas y los posibles cambios. • Método de Seguimiento: Es esencial tener una forma de averiguar todo sobre una decisión específica cuando sea necesario.

4 4 Motivo de la elaboración de este documento (3/3) Por tanto, considero los registros de decisiones arquitectónicas (ADR) como un complemento esencial a un modelo base de proceso de asesoramiento, apoyando y mejorando todos sus aspectos clave. Los ADR no solo nos ayuda a todos a tomar mejores decisiones, sino que también facilitan la búsqueda y el intercambio de asesoramiento de manera abierta. Lo mejor de todo es que los ADR mantienen un historial transparente y accesible de todas las decisiones, incluyendo el asesoramiento de apoyo. Esto contribuye significativamente a construir y mantener la confianza, además de ser un recurso valioso para el aprendizaje continuo. En este documento, utilizaré ejemplos para ilustrar cómo la redacción de ADR apoya tu proceso de toma de decisiones. Mostraré cómo la estructura de los ADR puede utilizarse para comprender el contexto de las decisiones y como un medio para pensar de manera estructurada sobre tus diversas opciones y sus consecuencias. También demostraré cómo los ADR proporcionan un apoyo invaluable para el funcionamiento fluido del proceso de asesoramiento, independientemente de cómo elijas gestionarlos y mantenerlos a lo largo de su ciclo de vida. Nota del autor Siempre que entro en un proyecto donde se desconoce este valioso activo, los ADR, encuentro la necesidad de explicarlo detalladamente. Por tanto, he creado este documento no solo para proporcionar una guía clara y estructurada sobre el uso de los ADR, sino también como una herramienta de presentación que me permite poner en contexto a todas las personas involucradas en el proceso de asesoramiento. Esto asegura que todos comprendan el valor y el impacto de los ADR en la toma de decisiones y en la construcción de confianza dentro de la organización.

5 5 ¿A quién va dirigido este documento? Este documento está dirigido a todos los profesionales involucrados en los procesos de asesoramiento arquitectónico y toma de decisiones dentro de la organización. Esto incluye personas del área de arquitectura, desarrollo, gerencia de proyecto y cualquier otra persona que participe en la planificación y ejecución de proyectos arquitectónicos. Además, es un recurso importante para aquellas personas que aspiran a convertirse en arquitectos/as, proporcionando una comprensión profunda de cómo los ADR pueden apoyar su desarrollo profesional y mejorar sus habilidades de toma de decisiones. Y quiero que el propósito de este documento sea doble: 1. Servir como una guía práctica para implementar y utilizar los ADR en tu organización. 2. Actuar como un recurso educativo para presentar y contextualizar los beneficios de los ADR a tu equipo y partes interesadas.

6 6 ¿Cómo está organizado este documento? (1/3) Introducción • Qué son los ADR: Los registros de decisiones arquitectónicas (ADR) son documentos que capturan decisiones importantes tomadas en el ámbito de la arquitectura de software, proporcionando un historial transparente y accesible de dichas decisiones. Su propósito es mejorar la toma de decisiones, facilitar el asesoramiento y construir confianza dentro de la organización. • Estructura de un ADR: Un ADR se compone de varios elementos principales, incluyendo el título, meta-elementos, la decisión tomada, el contexto de la decisión, las opciones consideradas, las consecuencias de cada opción y cualquier asesoramiento recibido. • Qué son las decisiones y cómo se aplica la responsabilidad: Tomar decisiones implica seleccionar una opción entre varias alternativas para resolver un problema o alcanzar un objetivo. Ser responsable, significa tener la obligación de rendir cuentas y ser transparente acerca de las decisiones tomadas, asegurando que se alinean con los objetivos y valores de la organización. • Estilos de Decisores y Cultura de Decisión: Existen varios estilos de toma de decisiones, desde decisiones centralizadas y jerárquicas hasta decisiones distribuidas y colaborativas. La cultura de decisión de una organización influye en cómo se toman las decisiones y quiénes son los decisores. Redacción para Apoyar la Toma de Decisiones • Paso 1: Crear un ADR vacío y establecer sus metadatos, como el autor, la fecha y el estado inicial. • Paso 2: Redactar el contexto de la decisión, proporcionando la información necesaria para comprender el entorno y las circunstancias en las que se toma la decisión. • Paso 3: Identificar las opciones disponibles y sus respectivas consecuencias, evaluando las posibles alternativas y sus impactos. • Paso 4: Proponer una opción seleccionada, justificando por qué se considera la mejor alternativa en base a la información y el asesoramiento recopilados.

7 7 ¿Cómo está organizado este documento? (2/3) Facilitar el Proceso de Asesoramiento • ¿Cuándo y cómo buscar asesoramiento?: Establecer estrategias claras para saber cuándo y cómo solicitar asesoramiento de manera efectiva, asegurando la participación de expertos relevantes. • Configurar la sección de asesoramiento: Organizar y recopilar el asesoramiento recibido de manera estructurada, facilitando su análisis y uso en la toma de decisiones. • Actualizar el ADR: Reflejar las contribuciones de otros en el ADR, asegurando que el documento se mantenga actualizado con la información más relevante y precisa. • La IA Generativa Tu Nuevo Asesor: El juego está cambiando y es momento de añadir nuevas herramientas que te ayuden. La IA generativa será tu primer filtro, ayudándote desde generar preguntas hasta redactar textos enfocados a los lectores. Veremos algunos prompts que pueden ser útiles en este proceso. • Las Spikes una herramienta de ayuda a la toma de decisiones. Tomar la Decisión y Completar • Seleccionar la opción de decisión: Elegir la mejor opción basada en el asesoramiento y análisis de las alternativas disponibles. • Redactar la sección de decisión y actualizar el título: Documentar la decisión final tomada y actualizar el título del ADR para reflejar con precisión su contenido. • Cambiar el estado del ADR a Aceptado: Finalizar el ADR cambiando su estado a Aceptado y compartir la decisión con las partes interesadas.

8 8 ¿Cómo está organizado este documento? (3/3) Ciclo de Vida • Estados estándar: Los ADR pasan por varios estados estándar a lo largo de su ciclo de vida, incluyendo Borrador, Propuesto, Aceptado y Suplantado. • Estados no estándar: Además de los estados estándar, pueden existir otras clasificaciones según las necesidades específicas del proyecto. Gestión • Aspectos fundamentales: Implementar principios sólidos para gestionar los ADR de manera eficaz, asegurando su relevancia y utilidad continua. • Mantenimiento y actualización continua de los ADR: Realizar una curaduría constante de los ADR para mantenerlos actualizados y reflejar las decisiones más recientes y relevantes. Conclusión • Resumen y recomendaciones: Recapitulación de los beneficios clave de los ADR y consejos prácticos para maximizar su valor en la organización, fomentando una cultura de transparencia, confianza y mejora continua en la toma de decisiones arquitectónicas. Más Información • Amplia tus conocimientos: Algunos enlaces que pueden resultar de utilidad.

9 9 Introducción a los ADRs (1/18) Qué son los ADR Los registros de decisiones arquitectónicas (ADR, por sus siglas en inglés) son documentos esenciales que apoyan todo el proceso de toma de decisiones en la arquitectura de software. Desde la identificación del problema, la evaluación de opciones, la toma de decisiones, hasta la comunicación del resultado, los ADR proporcionan un marco estructurado para documentar y compartir decisiones importantes de manera transparente. Los ADR no son un concepto nuevo. Fueron mencionados en un artículo de Jeff Tyree y Art Akerman en 2005 y luego popularizados por Michael Nygard en 2011, quien demostró cómo documentar adecuadamente el razonamiento detrás de una decisión en un sistema de software en evolución. Desde entonces, los ADR han ganado popularidad y se han adaptado a diversas tendencias y necesidades de la industria. Un ADR típico es un documento breve, generalmente de unas dos páginas, que registra una única decisión arquitectónica junto con la información de soporte relevante. Una vez que se ha tomado una decisión y se ha registrado en un ADR, esta se considera inmutable. Sin embargo, las decisiones pueden ser reemplazadas por decisiones posteriores, manteniendo un registro histórico valioso de las decisiones y prioridades del sistema de software.

10 10 Introducción a los ADRs (2/18) A continuación, se muestra el diagrama que ilustra el lugar de los ADR en el proceso de asesoramiento: En este documento, vamos a ver cómo redactar y gestionar los ADR para maximizar su efectividad en la toma de decisiones arquitectónicas y cómo mantener una biblioteca de ADRs que cuente la historia esencial del sistema de software, incluyendo tanto los aciertos como los errores. Decisión requerida Creación de opciones Toma de decisiones Compartir decisión Implementar decisión Buscar y recibir asesoramiento Los ADRs respaldan todas las etapas de la toma de decisiones

11 11 Introducción a los ADRs (3/18) Estructura de un ADR Independientemente de la herramienta utilizada para publicarlos, los ADRs están estructurados pensando en el lector más que en el escritor. Por esta razón, leer un ADR es mucho más sencillo que escribirlo. Utilizados para apoyar un proceso de asesoramiento, los ADRs completados tienen al menos las siguientes secciones en el orden que se muestra: Nombre de la Sección Descripción ID y Título Un identificador único y un resumen muy breve de la decisión en sí (por ejemplo, “ADR001—Usar Redis para Caché Distribuida”). Estado y Fecha Estado del documento ADR, los estados suelen ser "Borrador", "Propuesto", "Adoptado", "Superado" y "Retirado". Autor La persona (o equipo) que escribió el ADR y, por lo tanto, es responsable de él. Decisión La decisión tomada descrita en unas pocas frases. Contexto Las circunstancias contextuales actuales que llevaron a la decisión. Opciones Consideradas Cada opción considerada se describe brevemente, con pros y contras. Suele ser la opción propuesta/adoptada la que viene primero en esta lista. Consecuencias Las ramificaciones de seleccionar cada opción, tanto positivas como negativas.

12 12 Introducción a los ADRs (4/18) Título Implementación de Redis como Caché Distribuida El título es una declaración breve que transmite la esencia de la decisión. En este caso, el título deja claro que se tomó la decisión de implementar Redis como solución de caché distribuida. Meta-Datos • ID del ADR: ADR001 • Estado: Aceptado • Fecha: 2024-11-12 • Propuesto por: Jose María Flores • Decisores: Juan Gonzalez, Carolina Gómez y Jose María Flores Los meta-datos proporcionan información esencial sobre el ADR. El ID único elimina cualquier ambigüedad, el estado indica en qué fase del proceso de decisión se encuentra el ADR, y la fecha muestra cuándo se tomó la decisión. La sección "Propuesto por" identifica a la persona que inicialmente propuso el ADR, mientras que "Decisores" enumera a las personas responsables de tomar la decisión final.

13 13 Introducción a los ADRs (5/18) Aunque a veces solo se muestra "Autor/es" como la persona o personas que han tomado la decisión, considero importante reflejar todo el proceso completo en los meta-datos. Esto incluye quién propuso inicialmente la decisión y quiénes fueron los decisores, proporcionando un histórico visible sin tener que recurrir a otras herramientas como el repositorio de Git, Wiki o Confluence. Recuerda que este documento está diseñado para el lector, no para el autor. Decisión Implementaremos Redis como nuestra solución de caché distribuida. Esto implicará configurar un clúster de Redis con las siguientes especificaciones: • Número de nodos: 3 • Persistencia: Activada con snapshots RDB • Política de reemplazo: LRU (Least Recently Used) Esta sección declara la intención de la decisión y las acciones inmediatas para implementarla. No se incluyen detalles sobre los problemas que resuelve ni las opciones descartadas, ya que la sección está diseñada para apoyar a quien lea el ADR después de la decisión.

14 14 Introducción a los ADRs (6/18) Aunque a veces solo se muestra "Autor/es" como la persona o personas que han tomado la decisión, considero importante reflejar todo el proceso completo en los meta-datos. Esto incluye quién propuso inicialmente la decisión y quiénes fueron los decisores, proporcionando un histórico visible sin tener que recurrir a otras herramientas como el repositorio de Git, Wiki o Confluence. Recuerda que este documento está diseñado para el lector, no para el autor. Decisión Implementaremos Redis como nuestra solución de caché distribuida. Esto implicará configurar un clúster de Redis con las siguientes especificaciones: • Número de nodos: 3 • Persistencia: Activada con snapshots RDB • Política de reemplazo: LRU (Least Recently Used) Esta sección declara la intención de la decisión y las acciones inmediatas para implementarla. No se incluyen detalles sobre los problemas que resuelve ni las opciones descartadas, ya que la sección está diseñada para apoyar a quien lea el ADR después de la decisión.

15 15 Introducción a los ADRs (7/18) Contexto Actualmente, nuestra aplicación experimenta alta latencia en operaciones de lectura debido a la carga sobre nuestra base de datos principal. Queremos mejorar el rendimiento general y reducir la latencia utilizando una caché distribuida. • Problema: Alta latencia en las lecturas de la base de datos • Criterios de decisión: • Rendimiento: Mejora significativa en la velocidad de acceso a datos. • Escalabilidad: Capacidad de manejar cargas crecientes sin comprometer el rendimiento. • Simplicidad de implementación: Fácil de integrar con nuestra infraestructura existente. • Costos: Mantenimiento y operación dentro del presupuesto asignado. Esta sección proporciona los hechos y circunstancias que impulsan la decisión, así como los criterios utilizados para tomar la decisión.

16 16 Introducción a los ADRs (8/18) Opciones Consideradas (SELECCIONADA) Redis: • Pros: • Alta velocidad de acceso a datos • Soporte robusto y comunidad activa • Fácil de escalar horizontalmente • Contras: • Requiere configuración y monitoreo continuo Memcached: • Pros: • Muy rápido y ligero • Contras: • No ofrece persistencia de datos • Menor soporte para estructuras de datos complejas Hazelcast: • Pros: • Ofrece caché distribuida y procesamiento de datos en memoria • Contras: • Más complejo de configurar • Requiere más recursos de hardware Cada opción es descrita brevemente, indicando los pros y contras. La opción seleccionada se presenta primero, seguida de las opciones descartadas.

17 17 Introducción a los ADRs (9/18) Consecuencias Redis: • Beneficios: 1. Mejor rendimiento en la lectura de datos 2. Escalabilidad horizontal fácil de manejar 3. Persistencia de datos disponible • Desventajas: 1. Necesidad de monitoreo y mantenimiento continuo 2. Posibles costos adicionales de infraestructura Memcached: • Razones de rechazo: 1. La falta de persistencia de datos representa un riesgo significativo para nuestra aplicación, ya que cualquier reinicio del sistema resultaría en la pérdida de todos los datos en caché. 2. Menor soporte para estructuras de datos complejas que necesitamos manejar. Hazelcast: • Razones de rechazo: 1. La configuración y administración de Hazelcast es más compleja en comparación con Redis. 2. Requiere más recursos de hardware, lo que incrementa los costos operativos. 3. La comunidad y el soporte no son tan robustos como los de Redis. La sección de Consecuencias detalla por qué la opción seleccionada fue elegida y por qué las otras opciones fueron rechazadas. Se destacan tanto los beneficios como las desventajas de cada opción, proporcionando una visión completa del proceso de decisión.

18 18 Introducción a los ADRs (10/18) Asesoramiento • ¿Hemos considerado la escalabilidad futura de Redis? (José L., Ingeniero de Infraestructura, 11 Oct 2024) • ¿Qué medidas de seguridad implementaremos para proteger los datos en caché? (Laura M., Especialista en Seguridad, 10 Oct 2024) • ¿Se ha verificado la compatibilidad de Redis con nuestras herramientas actuales de monitoreo? (Andrés P., DevOps, 11 Oct 2024) • ¿Cómo afectará la implementación de Redis en nuestro presupuesto de infraestructura a largo plazo? (Marta R., Gerente de Finanzas, 20 Oct 2024) El asesoramiento recoge las contribuciones de diversos asesores, proporcionando una perspectiva amplia y sin filtrar. Este insumo ayuda a comprender cómo las opiniones y preocupaciones de diferentes partes interesadas influyeron en la decisión final. Este ejemplo de ADR técnico proporciona una estructura clara y concisa para documentar decisiones arquitectónicas. Al seguir esta plantilla, las organizaciones podrán asegurar que las decisiones son transparentes, bien justificadas y accesibles para todas las partes interesadas. Esta transparencia no solo facilita la implementación de decisiones, sino que también sirve como un valioso recurso de aprendizaje para futuros proyectos y equipos.

19 19 Introducción a los ADRs (11/18) Qué son las decisiones y cómo se aplica la responsabilidad En el contexto de la arquitectura del software se refieren a las decisiones arquitectónicas significativas como aquellas que afectan la estructura, las características no funcionales, las dependencias, las interfaces o las técnicas de construcción de un sistema. Criterios para Decisiones Arquitectónicas Significativas: • Estructura: Decisiones que afectan la disposición de las partes del sistema. • Características Transversales: Decisiones que afectan características no funcionales como el rendimiento, la seguridad, la escalabilidad, etc. • Dependencias: Decisiones que afectan cómo el sistema interactúa con otras partes que no controla, como servicios de terceros. • Interfaces: Decisiones que afectan cómo el sistema expone su funcionalidad a otros sistemas. • Técnicas de Construcción: Decisiones sobre las herramientas y técnicas utilizadas para construir y desplegar el sistema.

20 20 Introducción a los ADRs (12/18) Ejemplos de Decisiones Arquitectónicas y No Arquitectónicas: • Arquitectónicas: • Cómo dividir un módulo y establecer nuevos límites. • Qué equipos poseen qué servicios. • Qué formato usar para los logs y dónde enviarlos. • No Arquitectónicas: • Parámetros de ajuste para la rutina de recolección de basura de la máquina virtual. • La convención de nomenclatura para archivos y carpetas.

21 21 Introducción a los ADRs (13/18) Antes de ver la responsabilidad des, debemos ver ¿qué entendemos por asesoramiento?: El asesoramiento se refiere al proceso de buscar y recibir recomendaciones y consejos de personas con conocimientos y experiencia relevantes en un área específica. En el contexto de la arquitectura de software, el asesoramiento implica consultar a aquellos que serán afectados por una decisión y a expertos que puedan ofrecer perspectivas valiosas. Este proceso asegura que las decisiones se tomen de manera informada, considerando todos los ángulos y posibles impactos, lo que lleva a mejores resultados y a una mayor aceptación por parte de todos los involucrados. Por tanto, en el ámbito de la arquitectura de software, tener claro quién es responsable de tomar las decisiones importantes es crucial para que los proyectos tengan éxito. Tradicionalmente, esta responsabilidad recae en un grupo específico de arquitectos que tienen la autoridad de decidir sobre aspectos críticos del sistema. Sin embargo, este enfoque puede provocar retrasos y decisiones que no siempre reflejan las necesidades y conocimientos de los equipos de desarrollo. Para abordar estos problemas, se propone un enfoque descentralizado mediante un proceso de asesoramiento. Este proceso permite que cualquier miembro del equipo que necesite tomar una decisión importante pueda hacerlo, siempre y cuando busque y considere las opiniones de las personas que se verán afectadas por esa decisión y de aquellos con experiencia relevante en el área. Así, la responsabilidad y la rendición de cuentas se distribuyen de manera más equitativa, promoviendo una mayor colaboración y confianza entre todos los involucrados en el proyecto.

22 22 Introducción a los ADRs (14/18) Estilos de Decisores y Cultura de Decisión Sin perder de vista nuestro contexto, decisiones arquitectónicas en el software, existen varios estilos de decisores que pueden influir en cómo se toman y se implementan las decisiones. Estos estilos varían en función de la cantidad de poder centralizado o distribuido y de la velocidad con la que se pueden tomar las decisiones. Aquí os presento algunos de los estilos más comunes: • Decisión Autocrática: En este estilo, una sola persona tiene todo el poder para tomar decisiones. Esta persona recopila información y opciones por su cuenta y luego toma la decisión sin necesidad de consultar a otros. Aunque este método puede ser rápido, también puede ser arriesgado, ya que depende completamente del juicio de una sola persona. Ejemplo: Un CTO (Chief Technology Officer) de una startup decide unilateralmente adoptar una nueva tecnología sin consultar al equipo. • Decisión Delegada: Similar al estilo autocrático, pero con una diferencia clave: el líder delega la responsabilidad de tomar una decisión a otra persona que tiene más conocimiento o está más cerca del problema. Aunque la decisión sigue siendo rápida, la inclusión de otra persona puede mejorar la calidad de la decisión. Ejemplo: Un gerente de proyecto en una empresa de desarrollo de software delega la elección del framework de pruebas a un desarrollador senior porque tiene más experiencia en esa área.

23 23 Introducción a los ADRs (15/18) • Decisión Consultiva: Aquí, una persona toma la decisión final, pero lo hace después de consultar a varias personas para obtener sus opiniones y recomendaciones. Este método permite tomar en cuenta diversas perspectivas, aunque la decisión final sigue siendo centralizada. Ejemplo: En una consultoría de TI, un arquitecto de software toma la decisión final sobre la arquitectura del sistema, pero solo después de consultar a los desarrolladores, los expertos en seguridad y los stakeholders del negocio. • Decisión por Consentimiento: En este estilo, una persona toma la decisión, pero necesita el consentimiento de todos los afectados. Si alguien tiene una objeción seria, la decisión no puede avanzar hasta que se aborden esas preocupaciones. Esto equilibra la centralización con la necesidad de obtener aceptación de todos los involucrados. Ejemplo: Un equipo de desarrollo en una organización Agile decide implementar una nueva herramienta de integración continua solo después de que todos los miembros del equipo estén de acuerdo y no tengan objeciones serias. • Decisión Democrática: Las decisiones se toman mediante el voto de un grupo. Cada miembro del grupo tiene la oportunidad de votar por las opciones disponibles, y la opción con la mayoría de los votos es la que se adopta. Este método es muy inclusivo, pero puede ser lento y no siempre garantiza la mejor solución. Ejemplo: En una agencia digital, el equipo de diseño vota para elegir entre dos sistemas de gestión de contenido (CMS) para un nuevo proyecto de cliente.

24 24 Introducción a los ADRs (16/18) • Decisión por Consenso: En este estilo, todos los miembros del grupo deben estar de acuerdo con la decisión antes de que se implemente. Esto asegura que todos estén alineados y comprometidos con la decisión, pero puede ser un proceso muy lento y difícil de lograr. Ejemplo: Un equipo interdisciplinario en una gran empresa tecnológica debe decidir sobre una estrategia de migración a la nube y no procederá hasta que todos los representantes de los diferentes departamentos (desarrollo, operaciones, seguridad, etc.) estén de acuerdo con el plan. • Decisión Evitativa: A veces, la decisión es no tomar ninguna decisión. Esto puede ser útil en situaciones donde es mejor esperar a tener más información o cuando ninguna de las opciones actuales es viable. Sin embargo, evitar la decisión también puede llevar a la parálisis y la inacción. Ejemplo: Un comité de dirección en una empresa de consultoría decide posponer la decisión sobre la adopción de una nueva metodología de gestión de proyectos hasta que se disponga de más datos sobre su efectividad en otras empresas similares. Cada uno de estos estilos tiene sus propias ventajas y desventajas. La elección del estilo adecuado depende de la situación específica, la urgencia de la decisión, la naturaleza del problema y las dinámicas del equipo. En un entorno de desarrollo de software, es crucial encontrar un equilibrio entre la rapidez y la inclusión para asegurar que las decisiones sean tanto efectivas como aceptadas por todos los involucrados.

25 25 Introducción a los ADRs (17/18) Los estilos de decisores están intrínsecamente ligados a la cultura de decisión de una organización. La cultura de decisión define el entorno y las normas bajo las cuales se toman las decisiones y puede variar desde estructuras altamente centralizadas hasta aquellas que valoran la participación y el consenso. Sin embargo, es importante recordar que, como todo en una organización, la toma de decisiones es realizada por personas, y puede ocurrir que algunos individuos no estén alineados con la cultura predominante de la organización. Por ejemplo, en una empresa con una cultura de decisión colaborativa, un líder autocrático podría causar fricciones y desalineación dentro del equipo. Del mismo modo, en una organización con una cultura de decisión centralizada, un empleado que prefiera un estilo democrático podría sentirse frustrado y desmotivado. Recomendación para Alineación Para asegurar que todos los miembros de la organización estén alineados con la cultura de decisión, es fundamental fomentar una comunicación abierta y continua sobre las expectativas y los valores de la organización en relación con la toma de decisiones.

26 26 Introducción a los ADRs (18/18) Os pongo algunos pasos concretos: • Educación y Capacitación: Implementar programas de capacitación que expliquen claramente la cultura de decisión de la organización y los diferentes estilos de toma de decisiones. Esto puede incluir talleres, seminarios y sesiones de entrenamiento específicas. • Mentoría y Coaching: Asignar mentores o coaches que puedan guiar a los individuos que no están alineados con la cultura de decisión predominante. Estos mentores pueden proporcionar consejos y feedback constructivo para ayudar a los empleados a adaptarse. • Feedback Regular: Establecer mecanismos de retroalimentación regular donde los empleados puedan expresar sus preocupaciones y recibir feedback sobre cómo se están alineando con la cultura de decisión de la organización. • Modelado de Comportamiento: Los líderes deben modelar el comportamiento que desean ver en sus equipos. Si se espera una toma de decisiones colaborativa, los líderes deben demostrar este enfoque en sus propias decisiones. • Reconocimiento y Recompensas: Reconocer y recompensar a aquellos que ejemplifican los valores y prácticas de la cultura de decisión. Esto puede motivar a otros a alinearse y adoptar comportamientos similares.

27 27 Redacción para apoyar la toma de decisiones (1/14) Ahora que he compartido cómo creo que debería verse un ADR completo, voy a guiarte a través de otra decisión, pero esta vez escribiré este segundo ADR de ejemplo mientras avanzo. Mi objetivo es mostrarte cómo cada sección apoya la toma de decisiones en un proceso de decisión basado en asesoramiento. La decisión que voy a utilizar es un ejemplo que es habitual en mi día a día; este ejemplo está relacionado con la autorización y autenticación. A medida que te guío a través de las etapas del proceso de decisión, observarás que no estoy abordando las secciones del ADR en el orden en que aparecen en la plantilla. Además, visito algunas secciones en varias ocasiones. Esto se debe a que no estoy simplemente usando un ADR para "registrar una decisión". Más bien, estoy utilizando el acto de escribir para entender mi necesidad y contexto, para definir mis opciones y considerar sus consecuencias, para buscar y comprender el asesoramiento, y cuando eso esté hecho, tomar mi decisión. A medida que progreso, intenta ponerte en mi lugar. Ten en cuenta que soy el decisor, escribiendo el ADR para ayudarme a decidir. Como con todas las decisiones, cuando comienzo, no sé cuál será el resultado de la decisión. El acto de escribir me está ayudando a llegar allí. Nota del autor Como podéis observar no todos los ADRs son técnicos, también son funcionales, como el caso de la autorización y autenticación en una aplicación. Cuando se selecciona el ADR funcional podremos ir al técnico.

28 28 Redacción para apoyar la toma de decisiones (2/14) Paso 1: Crear un ADR vacío y establecer sus metadatos, como el autor, la fecha y el estado inicial El primer paso en cualquier decisión apoyada por un ADR es crear un nuevo archivo ADR a partir de tu plantilla. Si no tienes una, puedes usar una plantilla inicial descargada de un repositorio, como GitHub. Una vez creado, agrega un título provisional como “(BORRADOR) Flujo del proceso de Autorización y Autenticación” y un ID único (por ejemplo, ADR-002). Esto indica que el ADR está en el inicio de su proceso de decisión. Para los elementos restantes de metadatos dentro del ADR, establece el estado en "Borrador" y la fecha en la de hoy. El último detalle es agregar tu nombre (o el nombre del equipo que representas). Así es como se vería en esta etapa inicial: Título: [ADR-002] Flujo del proceso de Autorización y Autenticación Estado: Borrador Fecha: 2024-11-12 Autor: Jose María Flores Zazo Con la parte administrativa completada, podremos comenzar el proceso de toma de decisiones apoyado por la escritura. Nota del autor Los títulos de ADR deben indicar la decisión que se ha tomado. Sin embargo, al inicio del proceso de decisión, aún no sabes cuál será. Por lo tanto, es perfectamente normal que un título de ADR cambie varias veces hasta que se tome una decisión.

29 29 Redacción para apoyar la toma de decisiones (3/14) Paso 2: Redactar el contexto de la decisión, proporcionando la información necesaria para comprender el entorno y las circunstancias en las que se toma la decisión La sección de Contexto es donde aclaras por qué se requiere una decisión. Esto es esencial tanto para ti como para los futuros lectores, antes y después de que se tome la decisión. Las decisiones arquitectónicas siempre dependen de ciertas circunstancias, y es crucial conocer en qué depende la decisión. Ejemplo de Contexto para un Flujo de Autorización y Autenticación: Contexto: Estamos mejorando nuestro sistema de autorización y autenticación para aumentar la seguridad y evitar accesos no autorizados. El sistema actual utiliza autenticación básica con nombre de usuario y contraseña. Queremos implementar un sistema más robusto que incluya autenticación multifactor (MFA) y mejores prácticas de seguridad. Problema: El sistema actual presenta vulnerabilidades que podrían permitir a actores malintencionados acceder a cuentas de usuarios. Necesitamos un sistema más seguro que proteja mejor la información de nuestros usuarios.

30 30 Redacción para apoyar la toma de decisiones (4/14) Consejos para escribir el Contexto: • Reúne tus Pensamientos: Tan pronto como tengas los metadatos y el título provisional en su lugar, comienza a escribir la sección de Contexto. Esto te ayudará a clarificar tu entendimiento del problema y los factores clave que lo afectan. • Identifica los Factores Clave: Estos pueden incluir otros equipos, partes del sistema de software, costos, habilidades disponibles, herramientas (incluyendo pipelines), y más. No es necesario ser exhaustivo, pero es importante incluir requisitos funcionales y no funcionales, así como hechos técnicos y organizacionales relevantes. • Enfócate en el Problema: Al escribir el contexto, piensa solo en "¿Cuál es el problema?" y no en "¿Cuál es la solución?". Esto te ayudará a mantener la claridad y a no desviarte hacia posibles soluciones prematuras. • Utiliza Diagramas: Si has creado diagramas para entender el problema, considera incluir versiones legibles. Los diagramas simples pueden ser útiles para mostrar las partes principales, incluyendo aquellas bajo el control del equipo y las que no lo están. En esta etapa, los diagramas solo necesitan ser funcionales y no necesariamente presentables. • Busca Asesoramiento: No dudes en buscar asesoramiento sobre la sección de Contexto incluso antes de haber escrito cualquier otra cosa. Esto puede ayudarte a entender mejor el problema y a recibir input valioso desde el principio. Consejos para para describir bien el problema: • Claridad y Concisión: • Sé Claro: Asegúrate de que cualquier persona que lea tu descripción pueda entender el problema sin ambigüedades. • Sé Conciso: Evita la redundancia y utiliza frases directas. La brevedad ayudará a mantener el enfoque en lo esencial.

31 31 Redacción para apoyar la toma de decisiones (5/14) • Contextualiza el Problema: • Proporciona Antecedentes: Explica el contexto en el que surge el problema. Esto puede incluir la situación actual del sistema, las limitaciones existentes y los eventos que han llevado a la necesidad de una decisión. • Incluye Factores Relevantes: Menciona los factores técnicos, organizacionales y socio-técnicos que afectan el problema. • Identifica las Consecuencias del Problema: • Impacto en el Sistema: Describe cómo el problema afecta al sistema actual. Esto puede incluir aspectos como la seguridad, la eficiencia y la experiencia del usuario. • Riesgos Asociados: Señala los riesgos que el problema representa si no se resuelve adecuadamente. • Utiliza Ejemplos Concretos: • Casos de Uso: Proporciona ejemplos específicos que ilustren el problema. Esto puede hacer que sea más fácil de entender y relacionar. • Datos y Estadísticas: Si es posible, utiliza datos y estadísticas para respaldar tu descripción del problema. • Enfócate en el Problema, No en la Solución: • Evita Soluciones Prematuras: Mantén el enfoque en describir el problema sin proponer soluciones en esta etapa. Esto asegurará que el análisis del problema sea lo más objetivo posible.

32 32 Redacción para apoyar la toma de decisiones (6/14) Por tanto y tras ayudarnos de los consejos proporcionados y con alguna iteración, nuestro contexto y problema podría quedar definido de la siguiente forma: Contexto: Estamos mejorando nuestro sistema de autorización y autenticación para aumentar la seguridad y evitar accesos no autorizados. El sistema actual utiliza autenticación básica con nombre de usuario y contraseña. Queremos implementar un sistema más robusto que incluya autenticación multifactor (MFA) y mejores prácticas de seguridad.

33 33 Redacción para apoyar la toma de decisiones (7/14) Problema: El sistema actual de autenticación basado en nombre de usuario y contraseña presenta vulnerabilidades que podrían permitir a actores malintencionados acceder a cuentas de usuarios. Esto pone en riesgo la seguridad de la información sensible de nuestros usuarios y puede resultar en pérdidas financieras y de reputación para la empresa. Consecuencias: • Seguridad: Riesgo elevado de accesos no autorizados y posibles violaciones de datos. • Experiencia del Usuario: Potencial pérdida de confianza de los usuarios en la seguridad del sistema. • Cumplimiento Normativo: Posibles problemas de cumplimiento con regulaciones de seguridad de datos. Nota del autor Estas son consecuencias al problema, no consecuencia de las opciones que vamos a proponer para solventar este problema. Debemos tener claro que unas son posibles efectos adversos de lo que tenemos ahora y las otras son de lo que estamos planteando.

34 34 Redacción para apoyar la toma de decisiones (8/14) Paso 3: Identificar las opciones disponibles y sus respectivas consecuencias, evaluando las posibles alternativas y sus impactos Cuando se utilizan los ADR como herramientas de toma de decisiones, es esencial listar las opciones y sus consecuencias. Una vez que estés satisfecho con el contenido inicial de la sección de Contexto, es momento de generar el conjunto de opciones y recopilar los pros y contras de cada una. Consejos para Generar Opciones: • Empieza con lo Conocido: Comienza con las opciones que ya conoces. Es posible que hayas pensado en algunas soluciones desde el momento en que te diste cuenta de que se necesitaba una decisión. • Considera Alternativas: No te límites a las soluciones que inicialmente pensaste. Considera también las opciones de "no hacer nada" y "no hacerlo aún". Nota del autor Uno de los principales problemas que encuentro en las propuestas de arquitectura desde la consultoría es que a menudo se presenta solo una solución. Esto deja al cliente en una posición incómoda: si no le gusta la propuesta, debe pedir otra alternativa, lo que puede entrar en un ciclo difícil de romper. Al proporcionar varias alternativas, demuestras al cliente que tienes un conocimiento profundo del problema y que eres capaz de abordar la situación desde diferentes ángulos. Esto no solo incrementa la confianza del cliente en tu capacidad técnica, sino que también enriquece la conversación y facilita la toma de decisiones. De otra forma: proporcionar múltiples alternativas aumenta la transparencia, la confianza del cliente, facilita la toma de decisiones, evita la parálisis del análisis y permite la adaptabilidad.

35 35 Redacción para apoyar la toma de decisiones (9/14) • Utiliza la Sección de Contexto: La sección de Contexto puede proporcionar inspiración adicional y ayudar a afinar aún más tu comprensión del problema. • Sé Creativo: Generar opciones implica mucha creatividad. No dudes en tomar un enfoque creativo para pensar en posibles soluciones. • Captura Todo: Anota todas las opciones y sus consecuencias, aunque parezcan desordenadas al principio. Puedes organizarlas y refinarlas más tarde. • Evita Sesgos: No favorezcas una opción sobre otra ni escribas los pros y contras solo para validar tus sesgos. Captura todas las opciones con el mismo nivel de detalle. • Número de Opciones: Tener solo una opción es un mal indicio, y demasiadas opciones pueden llevar a la parálisis del análisis. Dos es el mínimo, y entre tres y cinco es un buen número. • Documenta Fuentes: Si encuentras información útil, asegúrate de documentar tus fuentes, preferiblemente con enlaces duraderos.

36 36 Redacción para apoyar la toma de decisiones (10/14) Opción 1: Implementar Autenticación Multifactor (MFA) • Pros: • Aumenta significativamente la seguridad. • Difícil de comprometer. • Contras: • Puede ser incómodo para los usuarios. • Requiere soporte adicional.

37 37 Redacción para apoyar la toma de decisiones (11/14) Opción 2: Utilizar OAuth 2.0 • Pros: • Estándar ampliamente adoptado. • Permite autenticación segura a través de proveedores externos. • Contras: • Complejidad en la implementación. • Dependencia de terceros.

38 38 Redacción para apoyar la toma de decisiones (12/14) Opción 3: Adoptar OpenID Connect con Federación • Pros: • Extensión de OAuth 2.0. • Simplifica la autenticación federada. • Contras: • Curva de aprendizaje.

39 39 Redacción para apoyar la toma de decisiones (13/14) Paso 4: Proponer una opción seleccionada, justificando por qué se considera la mejor alternativa en base a la información y el asesoramiento recopilados Finalmente, una vez que tienes un conjunto completo de opciones y sus consecuencias relacionadas, tanto pros como contras, puedes (si te sientes confiado) seleccionar provisionalmente una opción. ¿Deberías seleccionar provisionalmente una opción o no? Hay varias razones por las que podrías querer, o no, incluir una selección provisional. Aunque parezca que estás tratando de influenciar a tus asesores, seleccionar provisionalmente una opción les indica dónde deben enfocar su atención, ya que señala tu preferencia actual. Por otro lado, si estás en una posición de autoridad, podrías no querer incluir una decisión provisional porque el efecto ancla de la autoridad puede ser fuerte, a menudo más fuerte de lo que los que están en autoridad son conscientes. Los efectos de anclaje significan que otros tienden a estar de acuerdo contigo debido a tu posición y no por otras razones. Evita esto no seleccionando una opción. Incluso si no haces una selección, muchos asesores asumirán que tu opción preferida es la primera en tu lista. Asegúrate de que no se enfoquen excesivamente en lo que saben o asumen que es la opción seleccionada. Recuérdales que ofrezcan consejo sobre todas las opciones si lo desean y sugieran nuevas, así como cosas relacionadas con el contexto. Todo el ADR está abierto para consejos.

40 40 Redacción para apoyar la toma de decisiones (14/14) Si tomas una decisión provisional, asegúrate de actualizar el estado del ADR de “Borrador" a “Propuesto" y señala la opción que has escogido (añadir "provisionalmente seleccionada" junto a tu opción preferida será suficiente). Hacer ambas cosas deja claro a los lectores que has hecho una selección provisional. Si no estás tomando una decisión provisional, deja el estado como está. Ya sea que tomes una decisión provisional o no, no pierdas tiempo escribiendo la sección de Decisión. Doc as Code (documentación como código) La metodología de Documentación como Código (Doc as Code) está revolucionando la forma en que las organizaciones gestionan y mantienen su documentación. Al tratar la documentación de la misma manera que el código fuente, utilizando sistemas de control de versiones como Git, se obtienen numerosas ventajas y bondades. A continuación, se detallan algunas de las más importantes: • Trazabilidad y Control de Versiones. • Colaboración y Transparencia. • Automatización y Consistencia. • Calidad y Mantenimiento. • Seguridad y Control de Acceso. Para ello estoy trabajando en un modelo de documentación llamado ArcDoc+ que no está asociado a ningún fabricante (ya sea una Wiki de Azure DevOps, Confluence, GitHub Docs, etc.); uso docsify para generar la estructura donde podremos trabajar con Markdown y Mermaid. Y por supuesto aquí te puedes ayudar de la IA Generativa para documentar todo.

41 41 Facilitar el proceso de Asesoramiento (1/19) Además de ayudarte a pensar sobre una decisión en cuestión, los ADRs te brindan una manera de organizar y capturar el asesoramiento que recopilas a lo largo del proceso de toma de decisiones. También ayudan a garantizar que hayas buscado asesoramiento de todas las partes relevantes de manera transparente. Antes de hablar sobre cómo completar la sección de Asesoramiento de un ADR, discutamos cómo y cuándo buscar asesoramiento en general. ¿Cuándo y Cómo Buscar Asesoramiento? Recuerda, no hay un "mejor momento" para buscar asesoramiento. No necesitas esperar hasta la fase explícita de recopilación de asesoramiento. Aunque no hay reglas estrictas, existen algunas estrategias sobre cuándo, cómo y con qué frecuencia buscar asesoramiento. Al Inicio del Proceso de Decisión Puedes buscar asesoramiento tan pronto como tengas el primer borrador de tu sección de Contexto, un título provisional y nada más. Buscar asesoramiento temprano en el proceso de decisión involucra a más personas en la totalidad del problema, lo que es una buena manera de generar confianza y seguridad. Si eliges abordar tu decisión de esta manera, estás buscando que otros no solo te propongan opciones, sino que también ofrezcan su asesoramiento sobre las opciones y el contexto circundante. Recuerda a los asesores que deben tener cuidado con los sesgos personales hacia sus opciones preferidas.

42 42 Facilitar el proceso de Asesoramiento (2/19) Más Adelante en el Proceso de Decisión Puedes esperar hasta tener tus secciones de Contexto, Opciones y Consecuencias asociadas, y una sección de Decisión preliminar antes de buscar asesoramiento. Involucrarse más tarde puede proporcionarte comentarios más precisos y profundos enfocados en la decisión a la que se refiere tu ADR. Incluso puedes pedir asesoramiento sobre las secciones preliminares de Contexto, Opciones, Consecuencias y Decisión del propio ADR. De hecho, puede ser útil como solicitante de asesoramiento fomentar esto explícitamente. Fuentes de Asesoramiento El asesoramiento puede provenir de diversas fuentes: • Expertos en la Materia (SME): Personas con un conocimiento profundo y experiencia en el área específica relacionada con la decisión que estás tomando. • Documentación de Fabricantes: Información y guías proporcionadas por los fabricantes de herramientas, plataformas o tecnologías que estás evaluando. • Estándares ISO y otras Normas: Normas internacionales y mejores prácticas que pueden proporcionar una base sólida y reconocida para tu decisión. • Casos de Estudio y Ejemplos de la Industria: Ejemplos de cómo otras organizaciones han abordado problemas similares pueden ofrecer valiosas lecciones y perspectivas.

43 43 Facilitar el proceso de Asesoramiento (3/19) El Asesoramiento Puede Relacionarse con Cualquier Parte de la Decisión El asesoramiento podría y debería pertenecer a cualquier sección. A medida que tú y otros aprendan a buscar asesoramiento, sentirán cuándo es el mejor momento para hacerlo. El asesoramiento puede usarse para generar nuevas ideas (como más opciones), proporcionar mayor detalle (como afinar el contenido de la sección de Contexto), validar o contradecir (por ejemplo, consecuencias adicionales a favor y en contra de las opciones existentes), e incluso dividir la decisión en múltiples decisiones más pequeñas y potencialmente escalonadas. Es muy específico de la decisión y del individuo o equipo. Más de una Vez y Cuando Sea Necesario No estás restringido a una única sesión de asesoramiento con una persona determinada. Puedes volver a ellos tantas veces como sea necesario. El factor clave que el decisor debe tener en mente es enfocarse en una decisión sólida que entiendas y puedas respaldar, una que mantenga la confianza compartida que todos están cultivando cuidadosamente.

44 44 Facilitar el proceso de Asesoramiento (4/19) Acelerar la Toma de Decisiones Uno de los objetivos clave de un proceso de asesoramiento es acelerar la toma de decisiones. Progresar de manera incremental y aprender de los comentarios resultantes es mejor que pasar una eternidad tratando de tomar la decisión perfecta. Asegúrate de obtener el asesoramiento que necesitas, pero ten cuidado de no quedar atrapado en la fase de búsqueda de asesoramiento. Puntos clave para facilitar este proceso: • Progreso Incremental: Realiza avances pequeños y frecuentes para poder recibir retroalimentación constante y ajustar tu dirección según sea necesario. • Evitar la Parálisis por Análisis: Sé consciente de la tendencia a quedar atrapado en la fase de búsqueda de asesoramiento y trabaja activamente para evitarlo. • Validación y Ajuste: Usa el asesoramiento para validar tus decisiones y ajustarlas en consecuencia. Esto ayuda a evitar errores costosos y mejora la calidad de tus decisiones.

45 45 Facilitar el proceso de Asesoramiento (5/19) Configurar la sección de asesoramiento Antes de recopilar asesoramiento, necesitas saber de quién obtenerlo. En un proceso de asesoramiento, debes acercarte a dos grupos: las personas que se verán afectadas por la decisión y las personas que tienen la experiencia relevante. Asegúrate de poner realmente el esfuerzo en encontrar a todos aquellos que se verán afectados directamente, ya que el asesoramiento más valioso provendrá de ellos. Captura a estas personas/equipos en una lista con viñetas en tu sección de Asesoramiento. Este es un ejemplo de cómo se vería la lista en un ADR: Asesoramiento • Monica O., Gerente de Producto • Patrícia A. y Luis P., Enterprise Architecting Team • Clara N., Arquitecta de Soluciones del Producto • Normas y Estándares ISO de Seguridad relacionados con la GDPR: • ISO/IEC 27001:2013 - Tecnología de la Información - Técnicas de Seguridad - Sistemas de Gestión de Seguridad de la Información • ISO/IEC 27701:2019 - Extensión a ISO/IEC 27001 y ISO/IEC 27002 para la gestión de la información de privacidad - Requisitos y directrices

46 46 Facilitar el proceso de Asesoramiento (6/19) Incluso podrías incluir por qué la persona está en la lista. Consulta "Obtener Asesoramiento de las Personas Adecuadas" para más detalles. Con esto, es hora de recopilar el asesoramiento. Recopilación de Asesoramiento Organiza reuniones con las personas que te darán asesoramiento. Haz explícito a los posibles asesores que estás siguiendo el proceso de asesoramiento y cuál de los dos roles de ofrecimiento de asesoramiento cumplen. Usa el ADR para enfocar tu conversación con el asesor. Compartir tu ADR en su estado actual es una excelente manera de presentar tu pensamiento alrededor de una decisión antes de una conversación de asesoramiento. Esto establece la conversación, dejando claro lo que tienes y (por omisión) lo que no tienes en mente. Si te diriges en una dirección que el asesor considera completamente errónea, eso probablemente será evidente, y deberían señalarlo. Si te falta algo fundamental y vital, también será evidente. Si tu idea es sólida, pero te falta alguna información adicional de apoyo, eso también se destacará. Estás preparando la conversación al mostrar no solo en qué estás pensando, sino también cómo estás pensando en ello.

47 47 Facilitar el proceso de Asesoramiento (7/19) El asesoramiento que surge de una conversación respaldada por un ADR —cualquiera sea su estado de finalización— es casi inevitablemente mejor que uno que no lo está. No solo eso, sino que cuando además se registra "en bruto" en la sección de Asesoramiento, el asesoramiento es un excelente complemento al ADR como registro. Los ADRs sin la adición de la sección de Asesoramiento son resúmenes de decisiones después del hecho. Son una forma de compresión con pérdida de todo el proceso de decisión. Con la sección de Asesoramiento, los ADRs se convierten no solo en un registro del proceso de asesoramiento, sino también en un recurso de aprendizaje para el futuro. Este aprendizaje puede llegar en forma de retrospectivas o simplemente cuando desarrolladores y arquitectos se pregunten más tarde cómo se llegó al estado actual de las cosas o incluso cómo se trabajó esta decisión. Ambos son increíblemente valiosos. Para facilitar las cosas al asesor, ofrécete a ser el tomador de notas durante la sesión de asesoramiento. Trata de hacer diagramas si ayuda a aclarar y enfocar los asuntos. De esta manera, tendrás una razón para escuchar más profundamente, entenderás mejor y estarás más motivado para responder con preguntas clarificadoras en lugar de simplemente reaccionar a lo que escuchaste. Este tipo de escucha activa es una habilidad, y aunque puede llevar tiempo desarrollarla, vale la pena el esfuerzo ya que maximizas el valor que puedes obtener del asesoramiento compartido. Después de la sesión de asesoramiento, agrega las notas a la sección de Asesoramiento del ADR. Luego, comparte el ADR más las notas con el asesor para su validación. Recomiendo usar el método de aseguramiento negativo. Cuando compartas el ADR, explica que, si el asesor no ve nada incorrecto en las notas, no necesita realizar ninguna acción adicional. De lo contrario, pueden hacer correcciones hasta el punto de la toma de decisión, lo que resulta en que su intención sea capturada con precisión. O pueden pedirte que lo arregles en su nombre. Es importante hacer esto mientras la decisión aún está abierta, antes de que se haya tomado, para que se pueda aprovechar el asesoramiento recibido.

48 48 Facilitar el proceso de Asesoramiento (8/19) Ya sea que tomes notas sobre el asesoramiento que recibes o no, el asesor es responsable de asegurar que se refleje con precisión en la sección de Asesoramiento del ADR. Si eres el autor y lo agregas, asegúrate de volver a contactar con el asesor para que puedan verificar que has capturado su intención de manera clara y completa. "Clara y completa" es clave aquí. La sección de Asesoramiento del ADR necesita ser un registro preciso. Al final del proceso de recopilación de asesoramiento, el ADR tendrá el siguiente contenido validado en su sección de Asesoramiento, por ejemplo, se me ocurren las siguientes preguntas y por supuesto añadir las respuestas correspondientes: Preguntas para Monica O., Gerente de Producto: • ¿Qué nivel de confianza necesitamos garantizar a los usuarios sobre la seguridad de sus datos personales? • ¿Cómo afectaría una falla en el sistema de autenticación y autorización a la experiencia del usuario y qué planes de contingencia deberíamos tener? Preguntas para Patrícia A. y Luis P., Enterprise Architecting Team: • ¿Cómo se integrará el nuevo sistema de autenticación y autorización con la arquitectura existente? • ¿Existen dependencias críticas con otros sistemas que debamos considerar al implementar OAuth 2?0? • ¿Qué retos técnicos prevén en la implementación y mantenimiento del sistema de autenticación y autorización? Preguntas para Clara N., Arquitecta Soluciones del Producto: • ¿Podrías revisar y validar el diseño del flujo de autenticación y autorización que hemos propuesto para el Producto? • ¿Qué medidas de seguridad adicionales deberíamos considerar para cumplir con las normativas GDPR y las normas ISO relacionadas al Producto?

49 49 Facilitar el proceso de Asesoramiento (9/19) Actualizar el ADR Ahora es momento de considerar cómo el asesoramiento afecta tu ADR. Mientras estás bajo un proceso de asesoramiento, la toma de decisiones está en manos del equipo o del individuo que inició este proceso de decisión y de nadie más, pero los decisores están obligados por el contrato social a considerar cada punto de asesoramiento recibido. Incluso si aún estás seguro de que la mejor opción es evidente, revisa cada pieza de asesoramiento una última vez. La mejor manera de hacer esto es revisar cada sección de tu ADR a la luz del asesoramiento y hacer actualizaciones relevantes: • Añadir más información: Mejora las secciones de Contexto, Opciones o Consecuencias. Aprovecha esta oportunidad para incluir asesoramiento y opciones que no te gusten o con las que no estés de acuerdo. Recuerda, tienes el control de la toma de decisiones, así que no hay necesidad de mostrar sesgo o favoritismo. Sé transparente. • Aclarar: Si la información en tu ADR fue malinterpretada por los asesores, corrígela. Aprovecha esta oportunidad para asegurarte de que el texto del ADR sea lo más claro posible para que todos los lectores puedan entenderlo en el futuro. • Reconocer el asesoramiento: Ayuda mostrar en el texto principal del ADR cuando recibiste algún asesoramiento, pero decidiste no cambiar tu decisión como resultado. Una de las fortalezas clave del asesoramiento es que mitiga tus puntos ciegos. Si durante el proceso de hacer actualizaciones al ADR, queda claro que no entendiste suficientemente una pieza de asesoramiento, siéntete libre de volver a quien te lo ofreció.

50 50 Facilitar el proceso de Asesoramiento (10/19) Este acto de edición hace tu ADR mejor porque te fuerza a comprometerte directamente una última vez con el asesoramiento que has recibido, pero esta vez en la seguridad de un espacio más privado. También transforma tu ADR en un registro sólido del proceso de decisión. Al poner explícitamente el asesoramiento que consideras relevante en el cuerpo del ADR, le das el reconocimiento apropiado. También eliminas la necesidad de que otros lean todo el documento para beneficiarse de él. Supongamos que a raíz de estas conversaciones hemos obtenido información relevante para nuestro enfoque:

51 51 Facilitar el proceso de Asesoramiento (11/19)

52 52 Facilitar el proceso de Asesoramiento (12/19) Y ahora podremos actualizar nuestro ADR con una propuesta, completando todo lo anteriormente indicado (asesoramiento, diagramas que completan las opciones, etc.): Título: [ADR-002] Flujo del proceso de Autorización, Autenticación y Consentimientos. Estado: Propuesta Fecha: 2024-11-12 Autor: Jose María Flores Zazo Reordenamos las opciones y completamos con diagramas: (Provisionalmente Seleccionada) Opción 1: Utilizar OAuth 2.0 • Pros: • Estándar ampliamente adoptado. • Permite autenticación segura a través de proveedores externos. • Contras: • Complejidad en la implementación. • Dependencia de terceros.

53 53 La IA Generativa Tu Nuevo Asesor La inteligencia artificial generativa puede ser una herramienta poderosa para mejorar la eficiencia y la calidad del proceso de toma de decisiones en la arquitectura de software. Aquí hay algunas formas de incorporar la IA en este contexto, con ejemplos específicos para facilitar la comprensión. Generación de Preguntas para Asesoramiento La IA generativa puede ayudarte a formular preguntas relevantes y perspicaces para tus asesores. Por ejemplo, si estás considerando implementar un nuevo sistema de autenticación, puedes usar la IA para generar preguntas que aborden diferentes aspectos técnicos y de negocio. Ejemplo de prompt para Generación de Preguntas: "Genera una lista de preguntas para un arquitecto de soluciones sobre la implementación de Oauth 2 en un sistema de gestión de identidad y acceso." Resultado: • ¿Cuáles son los principales desafíos técnicos que anticipas en la implementación de OAuth 2? • ¿Cómo se integrará OAuth 2 con nuestros sistemas existentes? • ¿Qué medidas de seguridad adicionales debemos considerar para proteger las credenciales de los usuarios? • ¿Cómo afectará OAuth 2 a la experiencia del usuario final? Facilitar el proceso de Asesoramiento (13/19)

54 54 Redacción de Textos Enfocados a los Lectores La IA también puede ayudarte a redactar secciones completas de un ADR de manera clara y concisa, asegurando que el contenido sea fácilmente comprensible para todos los involucrados (respetando incluso sensibilidades lingüísticas, por poner un ejemplo). Ejemplo de Prompt para Redacción de Textos: "Redacta una introducción para un ADR sobre la implementación de OAuth 2.0, destacando sus ventajas y posibles desafíos.“ Resultado: "La implementación de OAuth 2.0 en nuestro sistema de gestión de identidad y acceso ofrece la ventaja de un estándar ampliamente adoptado que permite una autenticación segura a través de proveedores externos. Sin embargo, debemos considerar la complejidad en la implementación y la dependencia de terceros. Este documento explora estas ventajas y desafíos, proporcionando un análisis detallado para respaldar nuestra decisión." Facilitar el proceso de Asesoramiento (14/19)

55 55 Búsqueda en un RAG (Retrieval-Augmented Generation) de la Organización La IA puede facilitar la búsqueda de información relevante utilizando Retrieval-Augmented Generation, ayudándote a encontrar documentación, guías y ejemplos previos que pueden informarte mejor sobre la decisión en cuestión. Ejemplo de Prompt para Búsqueda en un RAG: "Busca en la organización ejemplos de implementación de OAuth 2.0 y cualquier documentación relacionada." Resultado: • Documento 1: "Implementación de OAuth 2.0 en Proyecto X - Guía de mejores prácticas." • Documento 2: "Casos de estudio sobre OAuth 2.0 en sistemas de gestión de identidad." • Documento 3: “Proyecto Portal del Empleado – [ADR-008] Implementación de OAuth2.0 con Consentimientos.“ Facilitar el proceso de Asesoramiento (15/19) Nota del autor El uso de RAG (Retrieval-Augmented Generation) puede romper los silos de conocimiento dentro de las organizaciones, ya que permite que la información crítica, que a menudo está aislada en manos de unos pocos, sea accesible y útil para todos.

56 56 Es crucial tener en cuenta los acuerdos y los posibles sesgos que pueden surgir al utilizar la IA en el proceso de toma de decisiones. La IA debe ser una herramienta de apoyo y no un sustituto del juicio humano. Seguridad de los Datos • Disponibilidad y Operatividad: La IA debe estar disponible y operativa según los términos acordados, garantizando que la información no salga de los modelos de la organización. Esto asegura que los datos sensibles y críticos estén protegidos contra accesos no autorizados. • Cumplimiento de Normativas: La precisión de las respuestas y recomendaciones de la IA debe cumplir con los estándares de seguridad y normativas definidas por la organización, incluyendo el cumplimiento de acuerdos de confidencialidad (NDA). Esto garantiza que la IA opere dentro de un marco seguro y regulado. Normativa y Cumplimiento • Cumplimiento de Estándares: La IA debe operar de acuerdo con los estándares y regulaciones internas y externas de la organización, asegurando que todas las recomendaciones y decisiones sean conformes a las políticas de seguridad y privacidad. • Protección de la Información: Los modelos de IA deben estar diseñados para proteger la información sensible, asegurando que no se filtren datos confidenciales y que se mantenga la integridad y confidencialidad de la información procesada. Facilitar el proceso de Asesoramiento (16/19)

57 57 Gestión de Sesgos • Verificación Humana: Siempre verifica las recomendaciones y respuestas generadas por la IA. Los sesgos pueden surgir en los datos de entrenamiento de la IA, y es esencial que un humano revise y valide la información. • Diversidad de Datos: Asegúrate de que los datos utilizados para entrenar la IA sean diversos y representativos para minimizar el sesgo. • Transparencia: La IA debe ser transparente en cuanto a cómo se generan las recomendaciones y qué datos se utilizan. Esto permite a los usuarios entender y confiar en las decisiones basadas en IA. Integrar la IA generativa en el proceso de toma de decisiones en la arquitectura de software puede proporcionar una ventaja significativa, desde la generación de preguntas hasta la redacción de textos y la búsqueda de información relevante. Sin embargo, es fundamental utilizarla como una herramienta complementaria, siempre verificando la precisión, gestionando los sesgos y asegurando que se cumplan los acuerdos de la organización. Al hacerlo, podrás aprovechar al máximo las capacidades de la IA mientras mantienes la calidad y la integridad de tus decisiones, además aumentarás considerablemente tu productividad enfocándote en los temas más complejos que redactar bien una frase (por ejemplo). Facilitar el proceso de Asesoramiento (17/19)

58 58 Spikes Las spikes son un complemento perfecto para un enfoque descentralizado de la arquitectura. No solo abordan la incertidumbre arquitectónica proporcionando retroalimentación concreta, sino que también investigan su tema en contexto. El objetivo de una spike es aprender de ella. Lo mejor de todo es que las spikes hacen esto sin tener que seleccionar una opción y llevarla a producción. Incluso cuando se lleva a cabo bien, el proceso de asesoramiento puede involucrar a muchas personas y consumir mucho tiempo. Las spikes sustituyen esta variabilidad costosa por una variabilidad más económica al ofrecer retroalimentación contextualizada a partir de código desechable, sin tener que seguir el proceso de asesoramiento o implementar la decisión resultante en producción. El código de una spike se escribe con el objetivo expreso de aprender, permitiendo un contacto temprano y significativo con un problema y reemplazando opiniones y conjeturas con hechos. Facilitar el proceso de Asesoramiento (18/19) Nota del autor Una spike, también conocida como "laboratorio" por algunos, es una investigación rápida y enfocada que se realiza para obtener información valiosa sobre un problema o una decisión arquitectónica sin comprometerse a una solución específica. Se utiliza para explorar y validar opciones antes de tomar una decisión final y llevarla a producción. Las observaciones realizadas durante una spike pueden luego informar la decisión subsecuente y la redacción del ADR correspondiente. Si eres un arquitecto/a que le gusta “mancharte de barro", este es el momento para involucrarte directamente en la práctica y obtener insights prácticos y accionables.

59 59 Facilitar el proceso de Asesoramiento (19/19) Decisión requerida Creación de opciones Toma de decisiones Compartir decisión Implementar decisión Los ADRs comienzan a escribirse aquí Las Spikes comienzan a crearse y validarse aquí Las spikes se sitúan al inicio del proceso de toma de decisiones, tocando los pasos cuando se define la decisión requerida y la creación de opciones. Comienzan en la etapa de "decisión requerida" porque es cuando se formula la pregunta o problema que la decisión resolverá. Una spike descubre y valida un conjunto de opciones, probando una o más de ellas, y saca a la luz pros y contras. Sin embargo, las spikes no llegan a evaluar en profundidad las opciones ni a presentarlas listas para la toma de decisiones finales. Por lo tanto, las spikes preceden y complementan la redacción de los ADRs.

60 60 Tomar la Decisión y Completar (1/6) Seleccionar la Opción de Decisión 1. Análisis de Alternativas: • Recolección de Datos: Se recopilan datos relevantes sobre cada opción, incluyendo sus ventajas y desventajas. • Evaluación de Consecuencias: Cada alternativa se evalúa en términos de su impacto en el sistema, costos, tiempo de implementación y riesgos asociados. • Consultas y Asesoramiento: Se busca asesoramiento de expertos y partes interesadas para obtener múltiples perspectivas y validar las opciones consideradas. 2. Métodos de Evaluación: • Análisis Costo-Beneficio: Comparar las ventajas y desventajas de cada opción en términos económicos. • Análisis de Riesgos: Identificar y evaluar los riesgos asociados con cada alternativa. • Métodos de Decisión Multicriterio (MCDM): Utilizar técnicas como el Proceso de Análisis Jerárquico (AHP) para ponderar y priorizar las opciones basadas en múltiples criterios. 3. Selección de la Opción: • Criterios de Selección: Definir criterios claros para la selección, como viabilidad técnica, alineación con objetivos estratégicos y facilidad de implementación. • Justificación: Documentar la razón por la cual se seleccionó una opción específica, destacando cómo esta opción satisface los criterios definidos y supera las alternativas.

61 61 Tomar la Decisión y Completar (2/6) Redactar la Sección de Decisión y Actualizar el Título 1. Documentación de la Decisión: • Sección de Decisión: Redactar una sección concisa y clara que describe la opción seleccionada, incluyendo el contexto, el problema abordado, y la justificación de la decisión. • Formato Estandarizado: Utilizar un formato estandarizado para asegurar la claridad y consistencia en la documentación. Esto típicamente incluye el título, estado, fecha, autor, contexto, problema, opciones consideradas, y la decisión final. 2. Actualización del Título: • Reflejo Preciso: Asegurarse de que el título del ADR refleje con precisión la decisión tomada. El título debe ser específico y descriptivo para facilitar la identificación y referencia futura. • Ejemplo: Si el ADR original era "Mejoras en la Autenticación", después de decidir implementar MFA, el título podría actualizarse a "Implementación de Autenticación Multifactor (MFA)".

62 62 Tomar la Decisión y Completar (3/6) Cambiar el Estado del ADR a Aceptado 1. Finalización del ADR: • Estado de Aceptación: Cambiar el estado del ADR a "Aceptado" para indicar que la decisión ha sido formalmente aprobada y está lista para ser implementada. • Fecha y Autor: Actualizar la fecha y confirmar el autor para mantener un registro claro de cuándo y por quién fue aceptada la decisión. 2. Comunicación: • Compartir con las Partes Interesadas: Distribuir el ADR aceptado a todas las partes interesadas y equipos relevantes. Esto asegura que todos estén informados de la decisión y preparados para su implementación. • Herramientas de Comunicación: Utilizar herramientas de gestión de proyectos y colaboración para facilitar la distribución y el seguimiento de la implementación de la decisión.

63 63 Tomar la Decisión y Completar (4/6)

64 64 Tomar la Decisión y Completar (5/6)

65 65 Tomar la Decisión y Completar (6/6)

66 66 Ciclo de Vida (1/4) Aspectos fundamentales Al igual que cualquier registro, los ADRs tienen ciclos de vida. Los estados de los ADRs no solo reflejan el estado de la decisión en cuestión, sino también el estado del ADR como un registro individual en la evolución de la arquitectura general. A continuación, se describen los estados más comúnmente utilizados para los ADRs, así como algunos estados no estándar que podrían ser útiles. Estados Estándar • Borrador: Indica que el ADR está en proceso de elaboración. Este estado se mantiene hasta que se toma una decisión provisional, momento en el cual el ADR pasa a estar en estado "Propuesto". Durante estos dos primeros estados, se busca asesoramiento y se evalúan las opciones. • Propuesto: El ADR está en revisión y se están recibiendo comentarios y asesoramiento. Una vez que se han proporcionado todos los consejos y se han satisfecho los calificadores, se puede tomar la decisión final. • Aceptado: La decisión ha sido tomada y aprobada. El estado del ADR cambia a "Aceptado" para indicar que la decisión está lista para ser implementada. • Reemplazado: Este estado se utiliza cuando una decisión posterior invalida o deprecia el ADR actual. Por ejemplo, si se hace una actualización significativa que reemplaza la decisión original, el ADR anterior se marca como “Reemplazado".

67 67 Ciclo de Vida (2/4) Crear Borrador Propuesto Aceptado Reemplazado Zona de búsqueda de asesoramiento Tomar decision provisional Tomar decision final Decision posterior reemplaza esta opción

68 68 Ciclo de Vida (3/4) Estados No Estándar • Expirado: Este estado se utiliza para decisiones sensibles al tiempo que necesitan ser revisadas después de un período determinado. Por ejemplo, si se elige un proveedor temporalmente hasta que el proveedor preferido esté disponible, el ADR puede expirar y ser revisado en un plazo (tres o seis meses). • Retirado: Utilizado cuando se está trabajando en la remediación de sistemas heredados. Indica que una decisión ha llegado al final de su vida útil y no tiene reemplazo directo. Es útil para marcar el ADR junto con el sistema al que pertenece como "Retirado". • Rechazado: Este estado ha sido menos útil en la práctica. En lugar de rechazar una decisión, es más efectivo documentar la decisión de no hacer cambios bajo un estado "Aceptado", con una opción seleccionada como "mantener el statu quo". No tienen por qué utilizarse todos los estados.

69 69 Ciclo de Vida (4/4) Aceptado Reemplazado Decision posterior reemplaza esta opción Expirado Circunstancias que hicieron relevantes el ADR han expirado Retirado Lo decidido ya no existe Rechazado Decisión no cumple con los criterios

70 70 Gestión (1/3) Mantenimiento y actualización continua de los ADR En el ámbito del desarrollo de software, el mantenimiento de la documentación en herramientas colaborativas como Wikis, Confluence y DocAsCode (DoC) en sistemas de control de código fuente es esencial para garantizar la accesibilidad y precisión de la información crítica. Estas plataformas y formatos permiten a los equipos de desarrollo registrar y compartir conocimientos, decisiones arquitectónicas y cambios en tiempo real, lo cual es vital para la transparencia y la eficiencia del proyecto. Dentro de este contexto, los Architecture Decision Records (ADRs) juegan un papel crucial al documentar las decisiones arquitectónicas clave, proporcionando un historial claro de las razones detrás de cada elección técnica. Gestionar los ADRs (Architecture Decision Records) no solo implica tratarlos de manera individual, sino también considerar su conjunto como una narrativa coherente de la arquitectura. Es crucial que esta historia sea accesible y fácil de entender. Una vez que tengas un lugar central para almacenar tus ADRs, es recomendable hacer que su contenido sea fácil de consumir. Esto maximiza el potencial de los ADRs como una biblioteca histórica de decisiones y un registro del historial de tus sistemas.

71 71 Gestión (2/3) La gestión de los ADRs puede incluir: • Crear una página de registro de cambios arquitectónicos que contenga enlaces a los ADRs gestionados. • Listar todos los ADRs no borradores en esta página, ordenados en orden cronológico inverso, del más nuevo al más antiguo. • Asegurarse de que todos los ADRs tengan un ID único. • Usar títulos claros que expliquen las decisiones. • Dar acceso a todos en la empresa a esta página, aunque sea solo en modo lectura para quienes no forman parte del área tecnológica. Con esta biblioteca de decisiones envolviendo tu colección de ADRs, tendrás un "registro de cambios" arquitectónico. Una vez que la página esté configurada y todos conozcan su propósito, se gestionará en gran medida por sí sola, pero puede requerir revisiones ocasionales para asegurar su completitud y orden correcto. Este registro de cambios es un recurso valioso. Anima a los nuevos empleados o transferidos a consultarlo durante su incorporación para familiarizarse con la arquitectura y la cultura. También puede ser útil para aquellos que buscan avanzar en su carrera y asumir más responsabilidades arquitectónicas.

72 72 Gestión (3/3) Para facilitar la comprensión, puede ser útil invertir en resúmenes o destacar los ADRs clave, que suelen ser aquellos con mayor impacto. La creación de estos resúmenes o destacados generalmente recae en alguien con un rol transversal en el equipo de arquitectura. Aunque crear resúmenes es más laborioso, ya que implica destilar y mantener contenido actualizado, puede ser muy útil. Alternativamente, destacar los ADRs clave es más sencillo y requiere menos mantenimiento. Estos ADRs clave son aquellos que marcaron puntos de inflexión importantes en la arquitectura, incluso si algunas decisiones fueron rechazadas tras una consideración cuidadosa. Nota del autor En el argot del desarrollo de software, este proceso se conoce como curate (curar), aunque he preferido usar términos más comunes en español. Curar en este contexto se refiere al acto de seleccionar, organizar y mantener información de manera que sea accesible y útil para los usuarios, asegurando que los registros y documentos importantes sean fáciles de encontrar y entender.

73 73 Conclusión En este documento os he mostrado cómo los ADRs (Architecture Decision Records) son una herramienta excelente para tomar mejores decisiones, buscar y ofrecer asesoramiento de manera abierta y, al considerarlos colectivamente, conocer las decisiones que otros han tomado o están en proceso de tomar. También os he mostrado cómo la estructura de los ADRs potencia el proceso de asesoramiento, y cómo, al ser colocados en el núcleo de las herramientas de desarrollo y adecuadamente gestionados, pueden formar la base del aprendizaje organizacional. Espero que, si no los usabas, comiences a integrarlos en tus procesos. Si ya los utilizabas, confío en que algo de lo presentado aquí te haya resultado útil para mejorar su implementación.

74 74 Más Información: Amplia tus Conocimientos Aspectos transversales a los ADRs • Shape your company’s decision style–and behaviors. • DiSC. • The Trust-Communication Trade-Off. • Confirmation Bias: A Ubiquitous Phenomenon in Many Guises. • 7 Strategies for Better Group Decision-Making. • What Is The Rule Of 40 For SaaS? Here’s How To Calculate It. • Teoría de la perspectiva: cómo tomamos decisiones de inversión. Aspectos técnicos a los ADRs • Architecture decision record (ADR) en GitHub donde podrás ver diferentes formatos. • https://adr.github.io/ • Proceso de ADR en AWS. • Architecture Decision Records en Microsoft Learn. • Cuando usar los ADR en Google Cloud.