He recibido comentarios sobre el documento de ADRs (muchas gracias)  y me han señalado dos puntos que requieren mayor claridad. Me tomaré un tiempo para actualizar una nueva versión del documento de ADRs (si te lo perdiste aquí tienes el documento y el artículo orginal), pero quiero compartir aquí algunas reflexiones al respecto. Faltaba una mayor extensión sobre qué decisiones necesitan ADRs y, además, me comentaron ciertos puntos sobre los ADRs que necesito desmitificar.

Descargate el documento

 

¿Qué decisiones necesitan una ADR?

A continuación, se presentan algunos escenarios en los que deberías considerar escribir una ADR:

  • Impacto en el desarrollo de software: Si la decisión afecta la manera en que los desarrolladores escriben el código, es crucial documentarla. Por ejemplo, elegir un nuevo framework de desarrollo o cambiar el estilo de codificación.
  • Decisiones costosas o difíciles de revertir: Cuando una decisión es difícil o costosa de cambiar, es importante seleccionar la mejor opción y asegurarse de que todos comprendan el razonamiento detrás de ella. Un ejemplo podría ser la elección de una base de datos principal para un sistema crítico.
  • Decisiones recurrentes: Si una decisión sigue siendo reconsiderada, perdiendo tiempo al reevaluar razones válidas de la decisión original, una ADR puede evitar esta redundancia. Por ejemplo, la elección de usar microservicios o monolito.
  • Preguntas frecuentes de nuevos miembros del equipo: Si la decisión es frecuentemente cuestionada por nuevos miembros del equipo, documentarla en una ADR puede proporcionar una referencia clara y consistente. Por ejemplo, la estructura de carpetas y módulos en el repositorio de código (esta siempre que entra un arquitecto nuevo tiene su propia opinión).
  • Adopción de decisiones externas: Si estás adoptando una decisión tomada por otro equipo o empresa, es recomendable crear tu propia ADR y referenciar la ADR original. Esto asegura que la decisión se ajuste a tu contexto específico y proporciona una base sólida para evaluar su aplicabilidad y hacer los ajustes necesarios. Por ejemplo, podrías adoptar un estándar de codificación de otra organización o implementar una práctica que no consideres ideal. En este último caso, es importante documentar tu desacuerdo de manera constructiva, explicando las razones y sugiriendo posibles mejoras o alternativas. Es crucial abordar estas situaciones con humildad y sin dejar que la arrogancia o los egos interfieran en el proceso.
  • Impacto duradero: Decisiones que tendrán un efecto prolongado y/o afectarán múltiples componentes o sistemas deben ser documentadas. Por ejemplo, la implementación de un protocolo de seguridad en toda la infraestructura.
  • Efectos externos al equipo: Si la decisión impactará a otros equipos o departamentos, es prudente usar la sección de Consulta para recopilar opiniones. Por ejemplo, la integración de un nuevo sistema de gestión de clientes que afectará a varios departamentos.
  • Complejidad: Decisiones complejas o difíciles de entender se benefician de una ADR para asegurar que todos los detalles estén claros. Por ejemplo, la elección de un algoritmo de cifrado específico.
  • Propuestas informales o RFCs: Si estás proponiendo un cambio de manera informal o mediante una solicitud de cambio (RFC), una ADR puede ayudar a recopilar retroalimentación y documentar la decisión final. Por ejemplo, proponer una nueva herramienta de CI/CD.
  • Innovaciones tecnológicas: Decisiones sobre la adopción de nuevas tecnologías o herramientas que pueden cambiar significativamente la forma en que se realizan las tareas. Por ejemplo, la incorporación de una herramienta de automatización de pruebas.
  • Estrategias de despliegue: Decidir entre diferentes estrategias de despliegue, como despliegue continuo (CD) frente a despliegue manual, puede afectar la estabilidad y la velocidad de entrega del software.
  • Estrategias de prueba: Elegir entre diferentes enfoques de prueba, como pruebas automatizadas versus pruebas manuales, puede influir en la calidad del software y en los tiempos de entrega.
  • Políticas de seguridad: Definir políticas para la gestión de contraseñas, autenticación de dos factores y control de acceso es fundamental para proteger los datos y los sistemas.
  • Normativas de cumplimiento: Implementar políticas para cumplir con regulaciones específicas, como GDPR o HIPAA, es crucial para evitar sanciones legales y proteger la privacidad de los usuarios.
Ejemplos de lo que no son ADRs

Para proporcionar mayor claridad, aquí hay una lista de ejemplos de decisiones que generalmente no requieren una ADR:

  1. Decisiones triviales: Cambios menores en el código que no afectan significativamente al proyecto, como la corrección de un error tipográfico.
  2. Preferencias personales: Elecciones basadas en gustos personales que no afectan al equipo ni al producto, como la preferencia por un tema oscuro o claro en el editor de código, generalmente no requieren una ADR. Sin embargo, si la decisión implica la elección de herramientas de desarrollo como Visual Studio Code, Visual Studio 2022 Community, Pro o Enterprise, sí podría necesitar una ADR. Esto se debe a que tales decisiones pueden tener implicaciones financieras y de cumplimiento de licencias (EULAs) que deben ser consideradas y documentadas.
  3. Decisiones temporales: Soluciones temporales o hacks que se implementan como una solución rápida y que se espera reemplazar pronto.
  4. Configuraciones específicas del entorno: Ajustes específicos a tu entorno de desarrollo local que no afectan a otros miembros del equipo ni a la producción.
  5. Herramientas de uso individual: Elección de herramientas que solo afectan a un individuo y no al flujo de trabajo del equipo, como un cliente de correo electrónico personal.
  6. Optimizaciones menores: Cambios menores de rendimiento que no tienen un impacto significativo en la arquitectura o en el rendimiento general del sistema.
  7. Documentación interna: Actualizaciones menores en la documentación que no afectan las políticas o los procedimientos del equipo.
  8. Estándares de codificación comunes: El uso de estándares de codificación ampliamente aceptados generalmente no requiere una ADR, ya que son prácticas bien establecidas y comúnmente adoptadas por la comunidad de desarrollo. Sin embargo, si se decide cambiar un linter establecido como el de AirB&B por el de otra compañía o incluso desarrollar nuestro propio linter, esto sí debería documentarse con una ADR. Este tipo de decisión puede tener un impacto significativo en el proceso de desarrollo, la consistencia del código y puede requerir una inversión de tiempo y recursos para implementar y adoptar el nuevo estándar.
  9. Decisiones ya consensuadas: Decisiones que ya se han discutido y acordado previamente, y que ya están siendo implementadas, generalmente no requieren una ADR. Por ejemplo, no tiene sentido crear una ADR para documentar cómo se almacenan los datos si el proyecto ya ha comenzado y, aunque no hubo una ADR formal, ya se decidió utilizar SQL Server. En estos casos, la decisión ha sido tomada y acordada por el equipo, y formalizarla en una ADR no aportaría valor adicional. Sin embargo, si en el futuro se considera cambiar de SQL Server a otra base de datos, esa nueva decisión sí debería documentarse con una ADR para asegurar una evaluación adecuada y la comunicación de las implicaciones del cambio.
  10. Actualizaciones rutinarias: Actualizaciones de software o bibliotecas que no introducen cambios significativos en la funcionalidad o en la arquitectura del sistema.

Al centrarse en documentar solo las decisiones que realmente necesitan una ADR, se puede asegurar que el proceso no se vuelva burocrático y que las ADRs sigan siendo una herramienta valiosa y eficiente para el equipo.

Creencias sobre la toma de decisiones

Desmentir algunas creencias sobre la toma de decisiones puede llevar a un proceso más claro y rápido. A continuación, se presentan algunas creencias ordenadas de mayor a menor impacto:

  • La toma de decisiones es un proceso lineal: La toma de decisiones debe ser un proceso dinámico y ágil, iterando sobre la ADR o la propuesta hasta que se alcance una decisión final y revisando decisiones pasadas según sea necesario. Cuanto más tiempo se posponga una decisión, más información se tendrá, pero las decisiones no pueden aplazarse indefinidamente. Registrar las decisiones es esencial para poder revisarlas y reutilizar la información y el análisis en ellas, ahorrando esfuerzo en futuras decisiones.
  • Más opciones mejoran la toma de decisiones: Contrario a lo que se podría pensar, ofrecer más opciones no siempre mejora la toma de decisiones. La investigación muestra que las personas son menos propensas a tomar una decisión cuando se les presentan demasiadas opciones y, además, son menos propensas a estar satisfechas con el resultado final. Evaluar numerosas opciones, cada una con sus pros y contras, puede resultar en una carga mental significativa. Donde sea posible, limita las opciones a no más de tres y utiliza herramientas visuales como calificaciones con estrellas y tablas para facilitar la comparación. Es importante no caer en el error de ofrecer solo una opción y esperar que el cliente solicite más si no está satisfecho, ya que esto puede reflejar negativamente en la percepción del arquitecto por parte del cliente (y creeme pueden pedir tu salida del proyecto).
  • Técnica de Evaluación con Pesos: Para tomar decisiones de manera más objetiva y matemática, una técnica útil es asignar pesos de 1 a 10 a cada pro y contra de las opciones consideradas. Esto permite comparar las opciones de forma más clara y estructurada. Por ejemplo: Configurar Redis Cache en Azure podría recibir un puntaje de 5/10 y
    montar Redis en AKS desde cero podría recibir un puntaje de 7/10. Esta técnica facilita la comparación y puede ayudar a tomar una decisión más informada.
  • La decisión debe ser tomada por la persona más senior: La persona con más autoridad no siempre es la mejor para tomar la decisión final. En cambio, la persona con mayor experiencia en el tema o quien será más afectada por el resultado debería ser la encargada de tomar la decisión. Esta persona, conocida como el propietario de la decisión, debe comprender el problema y las posibles soluciones, utilizando la investigación y las contribuciones de otros para fortalecer su conocimiento y llevar el proceso de decisión a una conclusión efectiva.
  • Todos los interesados deben participar en el proceso de retroalimentación: Cada interesado se verá afectado de manera diferente por la decisión. El propietario de la decisión debe asegurarse de que aquellos interesados que son cruciales para el éxito de la implementación tengan la oportunidad de dar su opinión y comprometerse con el resultado. Algunos interesados son útiles para consultar durante la redacción de la ADR, ayudando a identificar preocupaciones o vacíos en las opciones propuestas. Sin embargo, no todos los interesados necesitan estar involucrados en el proceso de toma de decisiones, aunque sí deben ser informados del resultado.
  • Debes solicitar todo tipo de retroalimentación: Es importante ser específico y adaptar las solicitudes de retroalimentación a cada interesado. La retroalimentación genérica a menudo no es útil para tomar una decisión y puede dificultar la identificación y uso de la retroalimentación relevante. Pide a los interesados involucrados que informen si algo en tu ADR o propuesta no está claro, hagan preguntas aclaratorias si lo necesitan y proporcionen retroalimentación solo cuando estén seguros de entender completamente. Puedes actualizar la ADR antes de que se decida para responder preguntas de los interesados o mejorar la claridad. Una vez tomada la decisión, comunícala a todos los interesados.
  • Todos los interesados deben estar de acuerdo con el resultado: Para que una decisión sea exitosa, los interesados deben comprometerse con el resultado, pero no todos necesitan estar de acuerdo en que es la mejor solución. Una vez que todos los interesados relevantes han sido consultados, el propietario de la decisión es quien tomará la decisión final. Luego, debe pedir a todos los interesados relevantes que se comprometan o no. Si algún interesado considera que el resultado es inseguro, debe explicar por qué, y el propietario de la decisión debe trabajar con ellos para abordar sus preocupaciones. Los interesados pueden indicar si están de acuerdo o en desacuerdo con la decisión, pero el compromiso es clave para el éxito. Cuando todos los interesados relevantes se han comprometido con el resultado, la decisión puede ser finalizada. Luego, la decisión no se revisará a menos que surja nueva información, en cuyo caso se iniciará un nuevo proceso de decisión cuyo resultado reemplazará la decisión original.
  • El propietario de la decisión puede tomar una decisión totalmente racional: Ya os comenté sobre los sesgos, se mencionaron algunos de los sesgos a los que todos estamos sujetos. El propietario de la decisión obtiene aportes de los interesados relevantes en un intento de mitigar al menos algunos de estos sesgos. Debes ser consciente de los sesgos que tú y otros involucrados puedan tener. Tener esto en mente ayudará, pero nunca podrás eliminar totalmente el sesgo. Requerir que los interesados se comprometan en lugar de acordar es una forma de mitigar el pensamiento grupal. Cuando los miembros del grupo no esperan un consenso total, es más probable que expresen puntos de vista disidentes y constructivos.
  • Las decisiones deben tomarse lo más rápido posible: Si bien es cierto que las decisiones no deben posponerse indefinidamente, apresurarse puede llevar a errores costosos. Es importante tomarse el tiempo necesario para recopilar información, consultar a los interesados clave y evaluar las opciones. Las decisiones apresuradas pueden pasar por alto detalles importantes y resultar en problemas a largo plazo.
  • Las decisiones una vez tomadas no deben revisarse: En un entorno dinámico, es crucial revisar y ajustar las decisiones a medida que se obtiene nueva información o cambian las circunstancias. La flexibilidad para reevaluar y modificar decisiones anteriores puede mejorar los resultados y adaptarse mejor a las necesidades actuales.
  • La toma de decisiones debe ser un proceso completamente democrático: Aunque es importante obtener retroalimentación de los interesados, la toma de decisiones no siempre puede ser completamente democrática. En muchos casos, un enfoque democrático puede llevar a un estancamiento o a decisiones subóptimas debido a la falta de consenso. En cambio, se debe equilibrar la inclusión de opiniones con la necesidad de tomar decisiones efectivas y oportunas.
  • Todas las decisiones deben ser respaldadas por datos: Aunque los datos son valiosos para la toma de decisiones, no todas las decisiones pueden basarse únicamente en datos. Algunas decisiones requieren juicio, experiencia y consideración de factores cualitativos que no pueden ser cuantificados fácilmente. En tales casos, una combinación de datos y juicio experto puede ser la mejor aproximación.
  • La retroalimentación negativa siempre es mala: La retroalimentación negativa puede ser constructiva y proporcionar información valiosa para mejorar las decisiones y los procesos. Es importante recibir y considerar la retroalimentación negativa de manera abierta y utilizarla para hacer ajustes que beneficien al equipo y al proyecto.

Conclusión

Espero que esta información os haya ayudado a comprender mejor qué decisiones necesitan o no una ADR y a entender el proceso de toma de decisiones.

Si tenéis más preguntas o necesitáis más aclaraciones sobre cómo tomar decisiones efectivas y documentarlas adecuadamente, no dudéis en preguntar. Estoy aquí para ayudar.