Documentar y comunicar la arquitectura

Te damos la bienvenida al Capítulo 4: Documentar y comunicar la arquitectura. Este capítulo muestra cómo describir una arquitectura de software para que las personas adecuadas la entiendan y para que la descripción siga siendo fiel a la realidad. Es práctico de principio a fin y usa una plataforma de reparto de comida como ejemplo recurrente, para que puedas comparar cada técnica sobre el mismo sistema.

Una arquitectura que solo existe en la cabeza de unas pocas personas es frágil. Nadie fuera de la sala puede revisarla, el próximo ingeniero que se incorpore no puede aprenderla, un auditor no puede comprobarla, y se va con las personas que la conocen. Es fácil equivocarse con la documentación en cualquiera de las dos direcciones. Los equipos que escriben demasiado poco pierden las razones de su estructura y repiten una y otra vez las mismas discusiones. Los equipos que escriben demasiado producen wikis en las que nadie confía. Así que el principio rector del capítulo es sencillo: escribe para el lector. Decide quién usará cada pieza de documentación y qué necesita de ella, escribe eso de forma breve y precisa, y no escribas nada más.

El capítulo está escrito para desarrolladores, arquitectos y líderes técnicos. Se basa en los capítulos 1 a 3: las decisiones y las estructuras que ahora hay que describir. Las secciones uno punto cinco, sobre las partes interesadas y las inquietudes, y uno punto seis, sobre las decisiones y los compromisos, son un contexto especialmente útil. Y lleva al Capítulo 5, que inicia el catálogo de estilos arquitectónicos, descritos con las herramientas que aprendes aquí.

El capítulo tiene ocho secciones. La sección cuatro punto uno se pregunta para quién es la documentación y cómo decidir qué merece ponerse por escrito. La respuesta corta: escribe a mano lo que el código no puede decirte y genera lo que el código ya expresa. La sección cuatro punto dos presenta la idea central de que un solo diagrama nunca basta. Una arquitectura se describe mediante varias vistas, cada una de las cuales responde a las inquietudes de determinadas partes interesadas. La sección cuatro punto tres convierte eso en el enfoque práctico más utilizado, el modelo C4 de Simon Brown, con cuatro niveles de zoom y un breve conjunto de reglas de notación que hacen que los diagramas se expliquen solos. La sección cuatro punto cuatro trata de las partes del Lenguaje Unificado de Modelado, o UML, que los arquitectos todavía usan, como los diagramas de secuencia y de máquina de estados, y de cuándo su precisión compensa el esfuerzo.

Este diagrama de la sección cuatro punto uno te ayuda a decidir cómo documentar cualquier información. El eje vertical pregunta si puede recuperarse a partir del código. El eje inferior pregunta con qué frecuencia cambia. Arriba a la izquierda: lo que el código no puede decirte y que cambia poco. El contexto y el alcance, los objetivos de calidad y las decisiones con sus razones. Escríbelos a mano y consérvalos. Arriba a la derecha: lo que cambia con más frecuencia, como las vistas de contenedores y de despliegue. Mantenlas junto al código y revísalas con cada cambio. Abajo a la derecha: lo que el código ya expresa y cambia a menudo, como los diagramas de clases y las referencias de la API. Genéralos en el pipeline. No los escribas nunca a mano. Y abajo a la izquierda: lo que puedes leer en el código y que cambia poco, como la pila tecnológica o los comandos de compilación. Basta con una breve referencia en un archivo README.

Este es el primer nivel del modelo C4 de la sección cuatro punto tres: un diagrama de contexto del sistema para la plataforma de reparto de comida. Arriba están los tres tipos de personas que la usan: clientes, personal de restaurantes y repartidores. Cada flecha está etiquetada con lo que hacen. En el centro está la propia plataforma, representada como una sola caja. Recibe pedidos, cobra los pagos, asigna repartidores y mantiene informado a todo el mundo. Debajo están los sistemas externos de los que depende: un proveedor de pagos, un servicio de mapas y los servicios push. En este nivel no hay tecnologías ni protocolos. Esos llegan en el siguiente nivel de zoom, el de los contenedores. Y fíjate en la leyenda. Todo diagrama C4 tiene un título y una leyenda, para que se explique solo.

Los diagramas muestran la estructura, pero rara vez muestran el porqué. La sección cuatro punto cinco trata de los registros de decisiones de arquitectura, o ADR: registros breves y fechados de una decisión cada uno, con un registro práctico completo para la plataforma de reparto. La sección cuatro punto seis muestra cómo una plantilla como arc cuarenta y dos da a toda la descripción una organización estándar, para que quienes escriben sepan qué cubrir y quienes leen sepan dónde buscar. La sección cuatro punto siete aborda el problema que derrota a la mayor parte de la documentación: quedarse obsoleta. Trata de escribir diagramas como texto, de publicar la documentación desde el pipeline de compilación y de los hábitos de propiedad que la mantienen fiel a la realidad. La sección cuatro punto ocho pasa de los documentos a las personas: adaptar el mensaje a directivos, desarrolladores, operaciones, personal de seguridad y auditores, explicar los compromisos y construir consenso cuando las personas discrepan.

Todas las técnicas de este capítulo sirven a un único objetivo: un entendimiento compartido y preciso del sistema entre las personas que lo construyen, lo operan, lo pagan y dependen de él. Una documentación pequeña, actual y con propietario, que vive junto al código, es mejor que un documento exhaustivo en el que nadie confía. Así que, si recuerdas una sola pregunta de este capítulo, que sea esta: ¿quién va a leer esto y qué hará con ello?

Puedes leer las secciones en orden o ir directamente a la técnica que necesitas hoy. Leer todo el capítulo lleva unas tres horas. Mientras avanzas, compara cómo cada técnica describe la misma plataforma de reparto de comida: como diagrama de contexto, diagrama de contenedores, diagramas de secuencia y de estados, registro de decisiones y resumen de una página. Cada sección termina con unas cuantas preguntas de autoevaluación. Respóndelas mentalmente antes de mirar. Cuando estés listo, haz la prueba opcional del capítulo: veinte preguntas de opción múltiple y dos respuestas escritas, en unos cuarenta y cinco minutos. La nota de aprobado es el ochenta por ciento.

Ese es el mapa del Capítulo 4. Empieza por la sección cuatro punto uno, donde vemos para quién es la documentación y cuánta merece la pena escribir. Nos vemos allí.