Parte 4: Visualizar la arquitectura del sistema técnico

Ya hemos cubierto la importancia de hablar con la gente para entender los desafíos y expectativas actuales, alinearse con los objetivos de la organización y recopilar o formular una visión del producto.

Otro paso crítico durante tus días iniciales como arquitecto de software es esbozar el estado actual de la plataforma, destacando sus características clave, problemas y ventajas.

¿Por qué?

¿Por qué deberías crear un diagrama que ilustre el estado actual del sistema? ¿El esfuerzo está justificado? Algunas personas descuidan documentar el estado actual de su software, ofreciendo lo que considero justificaciones débiles. Abordaré algunos argumentos comunes en este artículo y explicaré por qué son erróneos.

• La suposición de que todos en la organización conocen el sistema, aunque ampliamente sostenida, a menudo es incorrecta. Si bien todo el personal técnico podría estar familiarizado con la situación general del sistema, otros miembros de la organización típicamente no lo están. Los stakeholders clave en la evolución arquitectónica pueden no entender la necesidad de modificaciones técnicas a menos que el estado actual y sus desafíos se representen en un diagrama sencillo y se comuniquen efectivamente.

• “El código es documentación, y agregué algunos comentarios al repositorio que despliega nuestro sistema. Echa un vistazo a estos scripts Terraform increíbles; son perfectamente legibles”. Algunas personas son hábiles procesando información textual. Los genios podrían incluso interpretar YAML, visualizando su indentación como bloques de colores animados en sus mentes. Sin embargo, esto depende de conocimiento previo y un extenso background técnico adquirido a lo largo de los años. El impacto de una representación visual no puede compararse con explicaciones basadas en texto.

• No vale la pena el esfuerzo ya que estas visualizaciones pronto quedarán obsoletas. Este argumento tiene cierto mérito para diagramas de componentes o nivel de clase, pero generalmente es erróneo para representaciones de sistema de alto nivel. Transformar un sistema a ese nivel podría llevar meses o incluso años. Establecer una rutina para revisar la documentación cada tres meses, ya sea a través de tu plataforma de documentación o independientemente, funcionará. Los insights proporcionados al mantener visuales actuales superan el tiempo invertido trimestralmente para actualizarlos.

• El estado actual está podrido, así que preferimos documentar el estado objetivo directamente. Análogo a planear un viaje, conocer tu punto de partida es esencial para estimar la duración y determinar el medio de transporte más adecuado. La comunicación es clave: mientras tú conoces tu posición actual, otros podrían no. Para implementar cambios efectivamente o emprender proyectos adicionales, la gente necesita visualizar el viaje del punto A al punto B para comprender completamente la planificación. Elaboraré sobre esto en una próxima edición cuando presente herramientas de planificación.

Toolcard: Visión general del sistema actual

Introduje la caja de herramientas del Software Architect como un framework simplificado para guiarte a través de las tareas arquitectónicas estándar. Aumentémosla con una nueva herramienta: la Visión general del sistema actual. Todas estas tool cards son accesibles en una plantilla Miro: The Software Architect’s Toolbox en Miroverse.

Puedes comenzar este proceso desde el día uno ya que no necesitas depender de herramientas previamente introducidas, como feedback de stakeholders o la visión del producto. El estado actual no necesita sus artefactos resultantes.

Tengo algunos consejos para ti sobre cómo lograr esta tarea de la manera más eficiente posible.

Co-crear

Al crear una visión general del estado actual, evita suposiciones. Busca asistencia de otros más conocedores sobre partes específicas del sistema y recopila su feedback mientras elaboras el diagrama. Recuerda, ser arquitecto no significa que trabajes en aislamiento o que seas la persona más conocedora; tu rol es involucrar, comunicar y hacer brillar a otros.

Storytelling

Grabar una narración del diagrama de alto nivel de tu sistema es la mejor manera de presentarlo. Este enfoque te permite proporcionar contexto sobre la forma del sistema y la secuencia de decisiones que llevaron a su estado actual. Las discusiones sobre cómo representar mejor el estado actual (del aspecto de co-creación descrito arriba) pueden refinar esta narrativa.

Evita quejarte

No hay un sistema inherentemente “malo” o “bueno”, y el desarrollo de software no se trata solo de moverse de un estado problemático para “arreglarlo”. Las decisiones se tomaron dentro de contextos y restricciones específicos; no pueden simplemente etiquetarse como “buenas” o “malas”. Quizás fueron apropiadas en su momento, por ejemplo, si el objetivo era validar un caso de negocio.

Abstente de quejarte o culpar a otros al describir el viaje hacia el estado actual. En cambio, enfócate en los aspectos positivos.

Usa herramientas suficientemente simples

Podrías sentirte tentado a usar herramientas avanzadas que permitan ‘codificar’ el diagrama y mantenerlo en un repositorio git, con todas las ventajas que eso conlleva. Aconsejo en contra de esto por varias razones:

• La calidad de los resultados a menudo es pobre, particularmente en cuanto a las líneas de conexión, que pueden hacer que el diagrama sea confuso.

• Es fácil quedar atrapado en detalles técnicos sobre las herramientas y la configuración y asegurarse de que se renderice correctamente para propósitos de documentación.

• Realísticamente, pocas personas contribuirán a este diagrama general, y las herramientas de diagramación más populares soportan características colaborativas y control de versiones de todos modos.

Típicamente uso Miro para diagramar, pero hay numerosas otras herramientas adecuadas para esta tarea. A este nivel de zoom, debes ilustrar con cajas, flechas e iconos de usuario/sistema.

Consulta la página del framework MOSY para más detalles sobre un enfoque simple pero convincente que puedes elegir para describir y modelar tu sistema.

Fusionar y limpiar

Si hay documentación existente sobre el estado actual disponible, no la ignores. Cuando sea factible, úsala como fuente de inspiración. Consulta a los autores originales para obtener feedback sobre tus mejoras propuestas.

Para prevenir confusión, limpia cualquier diagrama desactualizado, actualiza todos los enlaces existentes y comunica claramente la ubicación de la nueva documentación.

Manténlo simple y evita detalles técnicos

El framework MoSy te permite mantener un alto nivel de abstracción, que puede servir como lenguaje común a través de todas las áreas de la organización.

Describe los actores, funciones y componentes en un estilo accesible para cualquiera, independientemente de su rol. La audiencia no es exclusivamente técnica. No uses acrónimos a menos que proporciones una leyenda o contexto para explicar sus significados.

Algunos ejemplos

Puedes revisar la plantilla Miro lista para usar para documentar sistemas con MOSY, que incluye una visualización de ejemplo.

Si tienes algún diagrama de ejemplo que te gustaría compartir conmigo y con la comunidad, ¡eso es fantástico! Por favor publica una imagen en los comentarios o envíame un mensaje.

¿Qué sigue?

Una vez que hayas mapeado cómo se ve tu sistema actualmente, puedes usar lo que aprendiste al hablar con stakeholders, los objetivos de la organización y la visión del producto para comenzar a trabajar en La Visión de Arquitectura. Esta parte resulta en otro documento lleno de diagramas, pero crearlo no es tan simple como solo mirar alrededor y hacer preguntas. Necesitarás trabajar estrechamente con otras personas para armarlo. Entraré en más detalle sobre cómo hacer esto en las siguientes publicaciones del blog.