Comunicar la arquitectura a distintos públicos

Comunicar es el trabajo

Una arquitectura que solo entiende su arquitecto ha fracasado, por buena que sea. Las decisiones determinan lo que decenas de personas construyen, operan, financian y auditan, y solo funcionan si esas personas las entienden lo bastante bien como para actuar en consecuencia y para darse cuenta de cuándo la realidad se aparta de ellas. Por eso el plan de estudios de iSAQB incluye la comunicación de la arquitectura entre las tareas centrales de un arquitecto, y por eso el rol del arquitecto descrito en el Capítulo 1 depende tanto de las habilidades interpersonales.

Las secciones anteriores de este capítulo aportaron el material: vistas, diagramas C4 y UML, ADR, una estructura arc42 y un pipeline que los mantiene al día. Esta sección trata de usar ese material con las personas. La habilidad central es la misma en cualquier situación: decide quién es el público, decide qué tiene que hacer después de escucharte y dale exactamente lo que eso requiere, en la forma en que pueda asimilarlo. La imagen del ascensor del arquitecto (architect elevator) de Gregor Hohpe (The Software Architect Elevator, 2020) recoge esa amplitud: un arquitecto sube y baja entre la sala del consejo, donde se fija la estrategia en términos de negocio, y la sala de máquinas, donde se construyen los sistemas, y tiene que hacerse entender en cada planta.

Adaptarse al público

Cada público tiene sus propias inquietudes, exactamente en el sentido de partes interesadas e inquietudes, y su propio vocabulario y capacidad de atención. La tabla es un punto de partida; la verdadera habilidad consiste en preguntarse, antes de preparar nada, ¿qué decidirá o hará de forma distinta esta persona después de esta conversación?

Dos hábitos ayudan con cualquier público. Empieza por la respuesta. Los lectores ocupados deben conocer la conclusión en la primera frase, después las razones que la respaldan y después el detalle; es la estructura que Barbara Minto enseñó a los consultores como el Principio de la Pirámide, y es la misma idea que la pirámide invertida de Fowler para los ADR. Usa sus palabras. Para una directora financiera, consistencia eventual es ruido; el restaurante ve un pedido nuevo hasta dos segundos después que el cliente, y no se pierde nada es un hecho que puede sopesar.

Explicar los compromisos

La mayor parte de la comunicación arquitectónica consiste, en el fondo, en explicar un compromiso. Quienes no son especialistas desconfían de las recomendaciones que parecen no tener ningún inconveniente, y hacen bien. Una estructura clara, usada de forma constante, hace que los compromisos sean fáciles de seguir: las opciones (incluida la de no hacer nada), los criterios que importan a este público, cómo sale parada cada opción, la recomendación y sus consecuencias, incluido aquello a lo que renuncias. Es la anatomía de una decisión del Capítulo 1 y el contenido de un ADR, adaptados a quien escucha.

El resumen de arquitectura en una página

Todo sistema se beneficia de un resumen de arquitectura en una página: una sola página que una persona recién llegada, un directivo o un revisor de otro equipo puede leer en cinco minutos. No sustituye a la documentación completa, sino que es su puerta de entrada. Una estructura útil es: qué hace el sistema y para quién (dos frases); los tres objetivos de calidad principales; un diagrama de contexto del sistema; un diagrama de contenedores o una lista de los bloques de construcción principales; las cinco o así decisiones que lo determinan todo (una línea cada una, con enlace a los ADR); los principales riesgos; y dónde encontrar más. La página arc42-lite de arc42 y plantillas es uno de esos resúmenes.

La disciplina de que la arquitectura quepa en una página es valiosa en sí misma. Si las ideas principales no pueden expresarse en una página, probablemente tampoco estén claras para el equipo.

Contar historias: seguir una solicitud

Las personas recuerdan mejor las historias que las estructuras. Una técnica eficaz para explicar cualquier sistema es seguir una solicitud: elige un único evento concreto e importante, como un cliente que hace un pedido, y recorre paso a paso lo que le ocurre a lo largo de la arquitectura. Un diagrama estático de cajas muestra lo que existe; la historia muestra por qué existe y cómo cooperan las partes. Además, revela de forma natural los momentos interesantes: dónde espera el cliente, dónde los datos cruzan un límite de confianza, qué ocurre si el proveedor de pagos va lento.

Elige la historia según el público. Para los desarrolladores, el camino feliz y después un fallo (ahora el proveedor de pagos agota el tiempo de espera). Para operaciones, el fallo y la recuperación. Para los directivos, la experiencia del cliente con solo los momentos relevantes para el negocio. Numera los pasos en el diagrama para poder señalarlos, y mantén el mismo diagrama en pantalla mientras hablas en lugar de saltar de una diapositiva a otra.

Pizarra y bocetos bien hechos

Gran parte de la comunicación arquitectónica ocurre en directo, ante una pizarra o en un lienzo compartido en línea, y unos pocos hábitos hacen que los bocetos sean mucho más útiles. Di lo que vas a dibujar antes de dibujarlo (este es el nivel de contenedores: cosas que desplegamos por separado), para que el público conozca el nivel de abstracción. Empieza por el contexto: los usuarios y los sistemas externos en los bordes, y después el interior. Etiqueta cada caja y cada línea a medida que dibujas, incluidos el sentido y lo que fluye; una flecha sin etiqueta la leerán de tres maneras distintas tres personas. Dibuja una pequeña leyenda en una esquina cuando uses más de un tipo de línea o de caja. Deja espacio, porque las mejores ideas llegan en mitad de la discusión y necesitan un sitio donde ir.

Los bocetos son herramientas para pensar y están hechos para tirarse, pero las conclusiones no. Fotografía la pizarra y, en el plazo de un día, convierte todo lo que vaya a importar en un diagrama en condiciones, un ADR o un cambio en la documentación. Simon Brown, creador del modelo C4, observó que los diagramas de pizarra de muchos equipos son cajas y líneas ambiguas precisamente porque carecen de un conjunto de abstracciones acordado; usar los niveles de C4 en la pizarra es una de las formas más sencillas de solucionarlo.

Documentos de diseño y RFC

Muchas organizaciones de ingeniería usan un documento de diseño escrito, a menudo llamado RFC (request for comments, solicitud de comentarios), para proponer un cambio significativo antes de construirlo. El nombre evoca la serie RFC de Internet, que empezó con el RFC 1 de Steve Crocker en abril de 1969. El autor expone el problema, el contexto, los objetivos y los no objetivos, el diseño propuesto, las alternativas consideradas y las inquietudes transversales como la seguridad, la privacidad y la observabilidad; el documento se hace circular entre las personas afectadas, que comentan por escrito; y se aprueba o se revisa. La muy leída descripción de Malte Ubl de los documentos de diseño en Google (2020) enumera exactamente esas secciones y sugiere de diez a veinte páginas para los proyectos grandes y de una a tres páginas para los pequeños minidocumentos de diseño. Gergely Orosz describió cómo Uber usó un proceso de RFC desde sus primeros años para difundir el conocimiento y detectar los problemas a tiempo (2018).

Amazon lleva la escritura más lejos: su carta a los accionistas de 2017 explica que la empresa no usa presentaciones con diapositivas en las reuniones, sino memorandos de seis páginas con estructura narrativa, que los asistentes leen en silencio al principio. El beneficio común a todas estas prácticas es que escribir obliga a pensar con claridad, los comentarios por escrito permiten contribuir a los compañeros más callados y a los que trabajan en remoto, y el documento se convierte en un registro. Los riesgos también son comunes: documentos largos que nadie termina, procesos de revisión que se convierten en barreras burocráticas y documentos de diseño que nunca se actualizan después de la implementación.

Los documentos de diseño y los ADR se complementan. Un documento de diseño explora un problema y propone un diseño completo, que a menudo abarca varias decisiones; una vez aprobado, las decisiones significativas que contiene se recogen como ADR, que son más breves, permanentes e indexados. Una regla razonable es: el documento de diseño, para pensar y persuadir; el ADR, para recordar.

Presentar en una revisión de arquitectura

Una revisión de arquitectura es una reunión en la que otras personas con experiencia examinan un diseño para encontrar riesgos antes de que salgan caros. Los métodos estructurados como ATAM y las revisiones más ligeras se tratan en Capítulo 11: revisiones ligeras; aquí lo que importa es cómo presentar bien. Envía el material al menos con dos días de antelación: el resumen de una página, los diagramas clave, los ADR pertinentes y los escenarios de calidad. Di al principio qué quieres de la revisión: una aprobación, una lista de riesgos o una elección entre dos opciones. Presenta los impulsores antes que el diseño, porque un revisor no puede juzgar un diseño sin saber qué cualidades debe lograr. Recorre uno o dos escenarios con la técnica de seguir una solicitud, incluido un fallo. Muestra los compromisos que asumiste y los riesgos que conoces; un revisor que encuentra un riesgo que ya habías enumerado confía más en ti, no menos. Anota cada problema planteado, con un responsable, y envía la lista después.

Reglas de diseño visual para los diagramas

Los diagramas comunican antes de que nadie lea una palabra, así que su diseño visual importa. Las reglas siguientes proceden de las pautas de notación de C4 de el modelo C4 y del diseño de información en general. El diagrama de antes y después las aplica a los mismos cinco elementos.

Gestionar los desacuerdos y construir consenso

Los desacuerdos sobre la arquitectura son normales y sanos: suelen significar que las personas ven riesgos distintos. El objetivo no es ganar, sino llegar a una decisión que las personas que tendrán que vivir con ella entiendan y apoyen. Varias prácticas ayudan.

Separa los intereses de las posiciones. Tenemos que usar Kafka es una posición; me preocupa que perdamos eventos durante los despliegues es un interés, y los intereses a menudo pueden satisfacerse de varias formas. Acuerda los criterios antes de comparar opciones, como en una matriz de decisión ponderada; la mayoría de las discusiones acaloradas son en realidad desacuerdos sobre lo que importa, y se enfrían en cuanto eso se hace explícito. Resuelve la incertidumbre con evidencias: un spike de dos días o una prueba de carga zanjan muchos debates que las reuniones no pueden zanjar. Ponlo por escrito: un ADR propuesto o un documento de diseño permite que todos comenten a su ritmo y da voz a los compañeros más callados.

Busca el consentimiento en lugar de la unanimidad. El RFC 7282 del IETF (Pete Resnick, 2014) describe el consenso aproximado: se llega a una decisión cuando se han abordado todas las objeciones, lo que significa que se han considerado y respondido, aunque no necesariamente atendido. Preguntar ¿hay alguien que no pueda aceptar esto, y por qué? saca a la luz los problemas bloqueantes más deprisa que preguntar si todos están de acuerdo. Cuando el consenso no es posible, alguien tiene que decidir, y debe estar claro de antemano quién. La carta a los accionistas de 2016 de Jeff Bezos popularizó el disagree and commit (discrepar y comprometerse): las personas expresan abiertamente su desacuerdo y después se comprometen por completo con la decisión una vez tomada. Registra la discrepancia y sus razones en el ADR; si quienes discrepaban acaban teniendo razón, el registro muestra qué hay que revisar y por qué.

Dos modos de fallo merecen una advertencia. El arquitecto que gana todas las discusiones por antigüedad deja de enterarse de los problemas. El equipo que no puede decidir sin unanimidad deja que las decisiones importantes se tomen por omisión, que es lo contrario del último momento responsable.