Documentación para registrar las decisiones de arquitectura en software e infraestructura

Escrito por picodotdev el .
planeta-codigo programacion
Enlace permanente Comentarios

Las tareas de un programador no consisten únicamente en escribir líneas de código o de un arquitecto decidir que usar o no usar y como. Una tarea importante de un programador o un arquitecto debe ser también escribir o mantener documentación actualizada. La arquitectura empleada en una aplicación permite conocer cuáles son sus componentes y piezas específicas de las que se compone sin tener que analizar el código fuente. La arquitectura de una aplicación puede ser de muchas formas, las decisiones de arquitectura también son un aspecto susceptible de ser documentadas, que permitan conocer cuáles fueron las motivaciones para elegir entre unas opciones y otras y que cambios de arquitectura ha sufrido una aplicación y por que motivos.

Al desarrollar una aplicación desde cero se han de tomar numerosa decisiones relativas a la arquitectura de la aplicación. Desde que lenguaje de programación a usar, que tecnología cómo que base de datos, si va a utilizar mensajes, el conjunto de librerías, si va a estar implementada con DDD o arquitectura hexagonal, que funcionalidades se implementan y como, como se va a hospedar y con que infraestructura entre muchas otras decisiones. La documentación es importante para conservar y transmitir el conocimiento sin tener que analizar el código fuente de la aplicación, ya sea de los componentes de arquitectura y cómo interactúan entre ellos o cuales son los requerimientos de un determinado proyecto para iniciarlo.

La arquitectura de una aplicación y los componentes de los que está formada una aplicación suelen documentarse con un esquema gráfico. Pero el esquema gráfico muestra únicamente la situación actual de la arquitectura y no es suficiente para conocer las motivaciones y requerimientos que han intervenido para optar por esa arquitectura y no otra, o los cambios que se han realizado en la arquitectura con el paso del tiempo.

Siempre se quiere tener documentación actualizada con la información que se necesita, a nadie le apetece extraer información a partir de código fuente ya que esto requiere mucho tiempo e impreciso. Querer documentación no es lo mismo que querer escribirla, pero normalmente es de gran ayuda para otros o para uno mismo en el futuro. Y no solo es escribirla sino también mantenerla actualizada.

Documentación Architecture Decision Records

La documentación de decisiones de arquitectura o Architecture Decision Records (ADR) es una colección de documentos que recogen individualmente cada una de las decisiones de arquitectura tomadas. Los ADR pueden ser simplemente un documento en Google Docs, una Wiki o una colección de documentos de texto en formato markdown. Como toda documentación esta requiere mantenimiento para que esté completa y no quede desfasada con el paso del tiempo, de modo que ha de sar fácil de mantener, accesible para su edición y tener visibilidad en la organización para encontrarla fácilmente.

Estas son siglas relacionadas con la documentación ADR:

  • AD: architecture decision, es una decisión de arquitectura tomada
  • ADR: architecture decisión record, es el registro con información relacionada de una AD.
  • ASR: architecturally-significant requirement, es un requerimiento destacado que influye en un AD.
  • ADL: architecture decision log, son el conjunto de los ADR.
  • AKM: architecture knowledge management

En los documentos ADR tienen las siguientes propiedades:

  • Fecha: cuando el AD ha sido tomada.
  • Razones: explicar las razones para tomar una determinada AD incluyendo los ASR.
  • Específico: cada ADR debe tratar un AD específico.
  • Inmutabilidad: los AD deben ser inmutables, no se ven afectados por decisiones futuras.

Cada ADR además puede recoger información de contexto, ya sea por la situación de una organización, prioridades de negocio o características o habilidades de los equipos. También pueden recoger otras informaciones como consecuencias de una AD, ya que las decisiones de arquitectura suele tomarse antes de implementarlas que riesgos tiene y que asunciones se están haciendo, ante esos riesgos que mitigaciones son posibles en caso de tener que optar por un cambio, que otras decisiones de arquitectura candidatas se han evaluado y por que se han descartado, o un análisis de arquitecturas por las que se han optado en otras organizaciones ante problemas similares.

Estos son algunos apartados de un ADR:

  • Fecha
  • Contexto
  • Decisión
  • Consecuencias
  • Riesgos
  • Mitigaciones
  • Candidatos evaluados
  • Asunciones
  • Restricciones
  • Argumentos

Un buen ejemplo de Architecture Decision Records son los documentos de especificaciones JEP de Java que incluyen un resumen, objetivos, motivaciones y una descripción detallada de la proposición.

Decisiones de arquitectura tomadas en mi blog

Utilizando como ejemplo mi blog a lo largo de los años he tenido que tomar varias decisiones que podrían ser de arquitectura. Entre Blogger, el generador estático de sitios web con Hugo y quizá en un futuro con AWS las cosas han cambiado mucho en mi blog, sin embargo, no he recogido en ningún documento específico cuáles son las decisiones en cada uno de esos cambios y los motivos.

El siguiente no sigue ninguna plantilla en concreto en los enlaces de referencia se incluyen algunas de ejemplo. Cualquier cosa relevante en la arquitectura es candidato a ser incluido en el ADR.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
# Creación blog

Fecha: 2010

### Contexto

Quiero un blog personal para escribir artículos técnicos relacionados con Java, de software libre y GNU/Linux y otros
artículos relacionados con la programación.
El mantenimiento no ha de ser complicado y el coste bajo o ninguno.

### Decisión

Uso Blogger como plataforma para tener un blog. Es rápido de tener, sencillo de usar y no
requiere conocimientos.

### Alternativa a Blogger

Fecha: 2013-12

### Contexto

Editar y publicar artículos con Blogger requiere un esfuerzo significativo. Personalizar la plantilla de Blogger no es
sencillo y propenso a errores.
Es difícil gestionar recursos de los artículos como imágenes y gestionar los enlaces entre los artículos.

Candidatos: Pelican, Octopress.

### Decisión

Cambio al generador estático Octopress y muevo el blog a GitHub Pages. Selecciono Octopress por tener documentación
específica para GitHub Pages.
No migro los artículos de Blogger a Octopress ya que requiere mucho esfuerzo.

---

# Alternativa a Octopress

Fecha: 2015-05

### Contexto

La instalación de la herramienta Octopress no es sencilla y es propensa a errores en local en las actualizaciones.
Octopress usa Ruby que no dominio de modo que los errores no se cual es el problema para solucionarlo rápidamente,
al mismo tiempo son poco descriptivos.

Candidatos: Hugo

### Argumentos

Hugo es un único binario fácil de instalar, es un generador estático de sitios web equivalente a Octopress pero mucho
más rápido en la generación del sitio, tiene numerosas opciones de personalización y buena documentación.

### Decisión

Empiezo a usar Hugo

### Riesgos

He de migrar el contenido de los artículos de Octopress a Hugo. El número de artículos a migrar es manejable y al estar
ambos en formato _markdown_ no se requieres grandes cambios.

---

# Alternativa a Gists

Fecha: 201?

### Contexto

Los trozos de código fuente que incluyo en los artículos los llevo almacenando como Gist de GitHub. Esto es parte del
contenido del artículo que está externalizado fuera.

### Acciones

Extraer el contenido de los Gist con un _script_ y ubicarlos como contenido de los artículos según la estructura de
directorios requerida por Hugo. Usar el editor para buscar y reemplazar en el contenido de los artículos de Gist al
contenido local.

### Decisión

Sustituir Gist por contenido local en el blog usando las facilidades de Hugo, _shortcodes_.

---

# Diseño adaptable

Fecha: 2019-05

### Contexto

El blog no es adaptable a diferentes tipos de pantalla, los bloques de publicidad solo se muestran
en la parte superior del artículo.

### Decisión

Hacer que el contenido del artículo tenga más anchura, sea adaptable y que un bloque de publicidad siga al contenido
al hacer _scroll_.

---

# Hospedaje en la nube y dominio propio

Fecha: 2021?
Estado: Proposición

### Contexto

Con el objetivo de aprender sobre computación en la nube, evaluar si migrar el blog a una nube. Y comprar un
dominio propio para independizarlo de la plataforma de hospedaje.

Candidatos: AWS, Linode o Digital Ocean.

### Argumentos

AWS tiene unos costes más variables que Linode o Digital Ocean pero algo más barato con un plan
de varios años, AWS es una opción más útil en ofertas de trabajo.

### Riesgos

El coste del blog con GitHub Pages es cero, el blog genera ingresos suficientes para cubrir los costes
de su hospedaje en la nube y el coste de un dominio propio. Con GitHub Pages no se requiere administrar
ni mantener infraestructura propia. Una nube requiere infraestructura propia y mantenerla.

Minimizar el impacto en el SEO, redirigiendo el tŕafico actual al nuevo dominio y haciendo que los buscadores
consideren el nuevo dominio como el canónico.

### Mitigaciones

En caso de que administrar infraestructura propia requiera tiempo o sea poco fiable una opción
es usar CloudFront + S3 en vez de CloudFront + EC2. El coste de S3 será algo más barato que usar EC2.
Durante el primer año la capa gratuita de AWS cubre la mayor parte de los costes. Con un dominio propio
en caso necesario quizá pudiese volver a GitHub Pages.

### Decisión

Migrar el contenido a una nube y adquirir un dominio propio.
adr.markdown

Comparte el artículo: