Registro de decisiones arquitectónicas

En un proyecto de software, las decisiones de alto nivel las puedes documentar en un formato estándar conocido como ADR (Architecture Decision Record). Los ADR son documentos cortos y claros que capturan información clave sobre decisiones arquitectónicas y de diseño importantes. A continuación, te explico cómo puedes documentar y compartir estas decisiones:

Formato típico de un ADR

  1. Título: Escribe un título descriptivo que resuma la decisión.
  2. Contexto: Explica el problema o situación que te llevó a tomar la decisión. Incluye antecedentes técnicos, restricciones y objetivos del proyecto.
  3. Decisión: Describe la solución o enfoque que seleccionaste, de manera clara y concisa.
  4. Razonamiento: Justifica la decisión, incluyendo pros y contras, alternativas evaluadas y las razones por las que las descartaste.
  5. Consecuencias: Detalla los efectos de la decisión, incluyendo beneficios, riesgos y posibles desafíos futuros.
  6. Fecha: Registra la fecha en que tomaste la decisión.
  7. Estado: Indica el estado actual de la decisión (por ejemplo, propuesta, aceptada, rechazada o reemplazada).

Buenas prácticas para documentar ADRs

  • Centraliza la información: Guarda los ADR en un repositorio accesible para todo el equipo, como un repositorio de código (por ejemplo, Git) o una herramienta de documentación (por ejemplo, Confluence o Notion).
  • Usa un formato consistente: Esto facilita que todos los interesados lean y comprendan los documentos.
  • Mantén los ADR actualizados: Si cambias una decisión, crea un nuevo ADR que documente el cambio y haga referencia al anterior.
  • Hazlos visibles: Proporciona enlaces desde herramientas de gestión de proyectos o bases de conocimiento para que los interesados los encuentren fácilmente.
  • Evita documentos excesivamente largos: Asegúrate de que los ADR sean breves y directos; si es necesario, incluye enlaces a documentación más detallada.

Aquí puedes consultar información sobre plantillas de ADRs.

Herramientas para gestionar ADRs

  1. Repositorios de código (Git): Crea un directorio docs/adr/ o similar para mantener los ADR versionados junto con el código.
  2. Herramientas colaborativas: Usa herramientas como Confluence, Notion o Google Docs para facilitar el acceso y la edición colaborativa.
  3. Plantillas: Usa plantillas prediseñadas para asegurar la uniformidad en todos los ADR.

Este enfoque te asegura que todos los interesados, incluidos desarrolladores, QA y stakeholders, tengan acceso a un historial claro y bien documentado de las decisiones clave del proyecto.

Gestión de ADRs con Azure DevOps

En un proyecto gestionado con Azure DevOps, puedes integrar los ADRs (Architecture Decision Records) de manera efectiva aprovechando las capacidades de documentación, repositorios de código y la integración con herramientas de colaboración que ofrece la plataforma. Aquí tienes un enfoque recomendado:

1. Usar un repositorio Git en Azure DevOps

  • Ubicación: Crea un directorio específico para los ADRs dentro del repositorio principal del proyecto, por ejemplo, docs/adr/.
  • Estructura: Guarda cada ADR como un archivo Markdown (.md) nombrado de manera secuencial y descriptiva, como 001-elegir-base-de-datos.md.
  • Ventajas:
    • Tienes versionado automático con Git.
    • Puedes enlazar a commits o pull requests que implementan la decisión.
    • Es compatible con revisiones a través de pull requests.

2. Wiki de Azure DevOps

  • Descripción: Usa la funcionalidad de Wiki de Azure DevOps para documentar los ADR en una sección específica.
  • Acceso: Asegúrate de que el Wiki esté accesible para todos los miembros del equipo y que tenga permisos de lectura para los stakeholders que no son desarrolladores.
  • Organización:
    • Crea una página principal llamada “ADRs” que enlace a páginas individuales para cada decisión.
    • Organiza las decisiones por fecha o categorías.
  • Ventajas:
    • Ofreces una interfaz amigable para no desarrolladores.
    • Facilitas la búsqueda y navegación.

3. Incorporar ADRs en Work Items

  • Enlace a Work Items:
    • Vincula los ADR relevantes a Work Items de Azure DevOps (por ejemplo, Epics, Features, o User Stories).
    • Usa el campo de descripción o los comentarios para incluir enlaces directos a los ADR en el repositorio o Wiki.
  • Beneficio: Esto permite que los desarrolladores y QA comprendan el contexto de decisiones arquitectónicas mientras trabajan en tareas específicas.

4. Automatizar con Azure Pipelines

  • Validación y consistencia: Configura Azure Pipelines para automatizar revisiones de ADR, como:
    • Verificar que los archivos estén en el formato correcto.
    • Asegurar que cada ADR tenga los campos requeridos (por ejemplo, contexto, decisión, razones, consecuencias).
  • Notificaciones: Configura notificaciones para el equipo cada vez que crees o modifiques un ADR.

5. Integración con Dashboards

  • Widgets personalizados: Usa los dashboards de Azure DevOps para mostrar:
    • Un resumen de los ADR más recientes.
    • Enlaces directos al repositorio o al Wiki.
  • Estado de las decisiones: Implementa un widget que muestre el estado de las decisiones clave (aceptado, en revisión, rechazado).

6. Políticas de mantenimiento

  • Actualización de ADRs: Define un proceso claro para actualizar ADR cuando cambien las decisiones.
  • Revisión periódica: Asigna responsables para revisar regularmente la relevancia y precisión de los ADR.

Ejemplo de flujo en Azure DevOps:

  1. Decisión inicial: Crea un ADR en docs/adr/001-elegir-base-de-datos.md.
  2. Discusión y aprobación: Revisa el documento mediante un pull request en Azure Repos.
  3. Implementación: Vincula el ADR a los Work Items relacionados.
  4. Documentación accesible: Refleja la decisión final en la Wiki y enlázala desde los dashboards o pipelines relevantes.

Este enfoque te asegura que los ADR estén centralizados, versionados y fácilmente accesibles para todos los miembros del proyecto, desde desarrolladores hasta stakeholders.