Por qué y cuánto documentar

Por qué hay que poner una arquitectura por escrito

Todo sistema tiene una arquitectura, la describa alguien o no (consulta la Sección 1.1). La descripción de arquitectura es otra cosa: los documentos, diagramas, modelos y registros de decisiones mediante los cuales las personas comparten un entendimiento de esa arquitectura. En un equipo de tres personas que trabajan juntas y escribieron cada línea, gran parte de la descripción puede vivir en su cabeza. En cuanto el equipo crece, alguien se va, se incorpora un segundo equipo, llega un auditor o el sistema sobrevive a sus autores, el conocimiento que solo existe en la cabeza de las personas se convierte en un riesgo. La definición de Ralph Johnson de la arquitectura como el entendimiento compartido de los desarrolladores expertos encierra una advertencia: un entendimiento que no está por escrito solo puede compartirse hablando, y hablar no escala.

Documenting Software Architectures: Views and Beyond (Paul Clements y sus colegas del Software Engineering Institute, 2.ª edición, 2010) señala tres usos de la documentación de arquitectura, y siguen siendo la forma más clara de pensar por qué merece la pena el esfuerzo. Forma: presenta el sistema a los nuevos miembros del equipo, a los revisores externos y a los nuevos arquitectos. Es el principal vehículo de comunicación entre las partes interesadas: desarrolladores, operadores, personal de seguridad y directivos discuten sobre el sistema a través de ella, y las decisiones alcanzadas en una reunión llegan a quienes no estuvieron presentes. Y es la base para el análisis y la construcción: indica a quienes implementan lo que pueden y no pueden hacer, y es lo que examina un evaluador cuando se pregunta si el sistema cumplirá sus objetivos de calidad (los métodos de evaluación del Capítulo 11 necesitan una descripción de la que partir).

De ello se derivan dos consecuencias. Primero, la documentación es un medio, no un fin: un documento que no sirve a ninguno de estos usos es un desperdicio, por bien formateado que esté. Segundo, es el lector quien decide si ha funcionado. Una descripción que su autor considera completa pero que un recién llegado no puede usar ha fracasado en la formación, y un diagrama que el equipo de operaciones no puede relacionar con los servidores reales ha fracasado en el análisis.

El software que funciona por encima de la documentación exhaustiva

El Manifiesto Ágil (2001) enumera cuatro pares de valores, uno de los cuales es Software que funciona por encima de la documentación exhaustiva. Se cita, a menudo, como permiso para no documentar nada. Leído completo, el manifiesto dice algo más acotado. Sus autores afirman que, aunque valoran los elementos de la derecha, valoran más los de la izquierda. El valor es una prioridad para cuando ambos compiten, no un rechazo de la documentación.

Lo que el valor rechaza es el proyecto dirigido por la documentación de la década de 1990: cientos de páginas de especificaciones aprobadas antes de escribir el código, tratadas como un avance en sí mismas y abandonadas en cuanto el código se aparta de ellas. La palabra que importa es exhaustiva: una documentación que intenta describirlo todo, como fin en sí misma, y que se valora más que el sistema en funcionamiento. Nada en el manifiesto se opone a un diagrama de contexto, a un breve registro de por qué el equipo eligió la mensajería asíncrona o a un runbook que permite al ingeniero de guardia restablecer el servicio a las tres de la madrugada.

Los profesionales sí discrepan sobre hasta dónde llegar. Algunos coaches ágiles sostienen que la conversación y las pruebas casi siempre bastan, y que la documentación escrita de arquitectura se queda obsoleta antes de amortizarse. Otros, sobre todo quienes mantienen sistemas de larga vida o trabajan en sectores regulados, señalan que las personas que más necesitan la documentación (los sucesores, los auditores, el equipo de operaciones) son precisamente las que están ausentes de las conversaciones. Ambas posturas coinciden en la economía subyacente: la documentación tiene un costo de escritura, un costo de mantenimiento y un costo de lectura, y solo merece producirse donde su valor para los lectores supera esos costos.

Documentación justa y necesaria

La expresión de Scott Ambler "just barely good enough" (apenas lo bastante buena) describe el objetivo: un modelo o un documento es suficiente cuando cumple su propósito para su público, y el esfuerzo más allá de ese punto cuesta más de lo que aporta. Su idea de que es el público, y no el autor, quien decide si un artefacto es suficiente es el mismo principio que escribir para el lector. George Fairbanks hace el argumento equivalente para el trabajo de arquitectura en su conjunto en Just Enough Software Architecture (2010): haz tanto como justifiquen los riesgos (consulta la Sección 1.8).

Por tanto, la documentación justa y necesaria no es una cantidad fija. Crece con el tamaño y la vida útil del sistema, el número de equipos, la rotación de personas, el costo de un fallo y las exigencias de los reguladores. Un prototipo de dos personas necesita un README y quizá un diagrama. Una plataforma de pagos gestionada por ocho equipos bajo regulación financiera necesita vistas de contexto, de contenedores y de despliegue, una bitácora de decisiones que se remonte años atrás, conceptos de seguridad documentados y evidencias de que los documentos se revisan.

Una señal práctica es la pregunta repetida. Si los recién llegados preguntan lo mismo en su primera semana, o la misma discusión de diseño vuelve cada pocos meses, la respuesta debe ponerse por escrito. Otra es el error costoso: si un equipo incumplió una regla no escrita ("no llamar nunca al proveedor de pagos desde la app de restaurantes") porque nadie se la dijo, esa regla era arquitectura y debería haberse puesto por escrito.

Qué merece documentarse y qué no

La información difiere en dos aspectos que deciden cómo debe documentarse. El primero es si puede recuperarse a partir del código. Los nombres de las clases, las firmas de los métodos y las tablas de la base de datos pueden leerse en el código fuente en cualquier momento; las razones por las que se tomó una decisión, los objetivos de calidad a los que sirve el sistema y las opciones que se rechazaron no, porque nunca estuvieron en el código. El segundo es con qué frecuencia cambia. El propósito del sistema y sus principales socios externos cambian poco; la lista de clases de un módulo cambia cada semana.

La documentación de arquitectura escrita a mano debe concentrarse en lo que es a la vez importante y no recuperable a partir del código: el contexto y el alcance del sistema (quién lo usa y de qué otros sistemas depende), sus objetivos de calidad y restricciones, las decisiones clave y sus razones, la estructura de grano grueso (las principales partes desplegables y sus responsabilidades), el despliegue sobre la infraestructura, los escenarios de ejecución importantes y los conceptos transversales que toda parte debe seguir, como la forma de gestionar los errores, de autenticar a los usuarios y de proteger los datos personales. Esta lista se parece mucho a la estructura de la plantilla arc42, que se trata en la Sección 4.6.

Lo que no merece escribirse a mano es todo lo que el código o las herramientas ya expresan con precisión y que cambia a menudo: los diagramas de clases de todo un código base, las listas de endpoints que ya contiene un archivo OpenAPI o las descripciones de cada función. Cuando esas vistas sean útiles, genéralas a partir del código fuente en el pipeline de compilación para que no puedan desviarse. Omite también el contenido aspiracional (diagramas de cómo debería ser el sistema, presentados como si ya lo fuera), las actas de reuniones cuyo resultado ya está recogido en otro lugar y el texto duplicado, que acabará contradiciendo a su copia.

Siete reglas para una documentación sólida

Views and Beyond establece siete reglas para una documentación sólida. Vale la pena saberlas de memoria, porque casi todos los fallos de documentación incumplen alguna de ellas.

Documentación viva y documentación como código

El fallo tradicional de la documentación de arquitectura es la obsolescencia: la descripción se escribe al principio, el sistema cambia y nadie actualiza el documento porque vive en un lugar separado del trabajo. Dos ideas relacionadas atacan este problema de raíz.

La documentación como código, una práctica promovida por la comunidad Write the Docs, consiste en tratar la documentación como código fuente: escrita en formatos de texto plano como Markdown o AsciiDoc, guardada bajo control de versiones (normalmente en el mismo repositorio que el código que describe), modificada mediante los mismos pull requests, revisada por las mismas personas y compilada y publicada por el mismo pipeline. Así, se puede exigir que un pull request que cambia la forma de asignar los pedidos actualice la vista de ejecución en el mismo commit, y el revisor ve ambas cosas.

La documentación viva, un término popularizado por el libro homónimo de Cyrille Martraire (2019), va más allá: siempre que sea posible, la documentación debe derivarse del propio sistema para que no pueda desviarse. Los diagramas de dependencias generados a partir del código, las referencias de API generadas a partir de archivos OpenAPI, las reglas de arquitectura comprobadas por pruebas automatizadas y los diagramas generados a partir de un modelo guardado junto al código son ejemplos de ello. El texto escrito a mano se reserva para lo que no puede derivarse, principalmente la intención y la justificación.

Ninguna de las dos ideas elimina la necesidad de criterio sobre qué escribir. La Sección 4.7, Diagramas como código, trata en detalle las herramientas y los hábitos.