Intención

Durante muchos años de desarrollo en los que estuve involucrado, en diferentes sectores empresariales, así como en diferentes conversaciones o comentarios entre desarrolladores y arquitectos de software, existe una brecha, cuando hablan específicamente de como mapear un componente en un repositorio y si ver que ¿efectivamente está acorde al diseño y solución propuesto?, y sobre todo, ¿cómo es que alguien del equipo en un menor tiempo puede aprender más allá de una exploración?

Estos últimos años en la era digital, dos de los cuatro ismos se han vuelto muy necesarios con respecto al desarrollo y visto desde otro punto de vista son:

• Inmediatismo: Consumir, utilizar u obtener toda información de la manera más rápida posible

• Facilismo: Lograr el objetivo sin mucho esfuerzo, que debe de hacerse de alguna manera que no implique esfuerzo

• Fragmentarismo: Sea muy breve y conciso, con la capacidad de aclarar

Comparto un punto de vista que debería tener un documento readme.md de un repositorio, que podría tener o ver la forma más rápida de entender lo que hace y el propósito

Motivación

Sabemos que la arquitectura de solución es un elemento fundamental en una organización y que el enfoque es abordar las necesidades de todas las partes interesadas y establecer un estándar que cubra la brecha entre los requisitos de negocio y las soluciones técnicas. Posteriormente, esto pasa a las manos de arquitectura de software, donde entra a una mayor definición de componentes, y generación de diferentes puntos de vista y que están alineados con los atributos de calidad.

Finalmente, pasa por una etapa de diseño, donde existe una mayor refinación para la implementación y creación necesaria de todo componente que sea útil para cumplir la arquitectura definida, posterior a ello existe una documentación donde se detalla todos los componentes utilizados para la funcionalidad que necesita el negocio.

Existe un desafío cuando se solicita cambios, o requieren modificaciones que implican un conocimiento más profundo de la solución implementada, se realizan los cambios, pero toma un tiempo, en especial cuando el conocimiento no es compartido, o no lo tiene en su totalidad, normalmente no volveremos a encontrar al developer ya sea por tiempo o porque simplemente ya no forma parte del equipo.

Luego de años de revisar diversas fuentes de información (arc42, UML, C4, Libros de SEI, Universidad) así como también la participación técnica en diferentes empresas, pude dar un bosquejo inicial de como podría ir una propuesta de documentación. Es decir, ver con otra óptica el punto final y que es imprescindible porque aquello al final es parte de la solución esperada por el negocio.

Inspiración o ¿a partir de donde nació la idea?

Siempre que escuchan esto: “Soy un desarrollador/programador, escribo poesía entre líneas, no documentas la poesía” (las versiones varían, pero al final su punto es ese), y para un desarrollador es abrumador, o al menos si se trata de documentación extensa, o sobre todo cuando piden el documento para revisión de estos componentes.

Nuevamente, esto es una idea inicial y que tiene puntos que faltaba madurez o mayor especificación, y todos los comentarios son bienvenidos, recordando siempre ese punto de vista, el del desarrollador/programador.

Documentación técnica

llegamos al punto, sin más preámbulos comenzaré el punto que debería abordar una documentación técnica, una vez más, esto es solo un modelo que puede mejorar recibir sugerencias, recordemos que este tipo de documentaciones no es para nosotros, sino para algún futuro interesado en saber el “como” funciona.

Nombre del artefacto:

Que realiza o almacena el repositorio, ¿recibe o almacena información de personas?, ¿almacena información y es almacenado en una base de datos?, La descripción debe de ser breve y muy específica.

Diagrama de componentes

Este puede ser el punto que tiene mayor detalle y en mi opinión la más importante, primero comenzamos colocando el nombre del artefacto, solución, nombre de repositorio, código de asignación de despliegue, unidad aplicativa, como quieran llamarlo basándonos en el contexto que crean necesario, en este caso nos enfocaremos en un componente que realiza suscripciones por correo

Definición de componente principal

Para este caso email-subscription es un backend hecho en java y tendrá una base de datos propia a la cual se conecta para almacenar los correos. La dirección de la flecha indica que el email-subscription hace uso de la base de datos

¡Antención!: La lectura de esto es:

• email-subscription utiliza, lee, accede, obtiene, conecta a una base de datos PostgreSQL

Mantendremos esta notación debido a que lo que se quiere conocer es como se comunica el componente desarrollado con otros.

Añadiendo componente externo

Ahora, añadiremos otro elemento, por ejemplo, validar cada correo por medio de un servicio de terceros antes de almacenar los correos, para este caso existen dos consideraciones:

• El componente se coloca de color plomo debido a que es una caja negra o tenemos una responsabilidad limitada

• Colocar un nombre de conector, es decir, se necesita saber como inicia, por ejemplo ahora indica que email-subscription solicita información a Email validator y luego almacena en base de datos

Añadiendo componente propio

Supongamos que ahora necesitamos que nuestro email-subscription requiera a otro servicio para verificar si son usuarios que realizaron pagos, y que este es otro backend, pero que construimos nosotros u otro equipo, para ello tener las siguientes consideraciones

• como es un componente que está dentro de nuestro conocimiento o contexto, este debe de tener un color para diferenciarlo, en este caso un celeste.

Recordemos que solo nos importa el repositorio o artefacto que estamos documentando, no importa si los componentes (color celeste) tienen alguna conexión o se comunican con otros servicios, eso no corresponde documentar.

Colas de mensajería

Una vez que se verifica los correos suscritos y si algunos correos tienen pagos realizados, enviaremos a dos colas de mensajería a los que está suscrito, uno propio (PubSub - GCP)y el otro de un tercero (SQS - AWS). Para este punto añadimos la leyenda de los elementos que se utilizan.

A este punto podemos determinar que nuestro componente principal es de color verde, el resto de componentes están delimitados por un color y los conectores indican cuál es el flujo con base en la enumeración que sigue con los componentes.

Hasta ahora el diagrama solo indica que tiene comunicación de forma síncrona y asíncrona con una numeración, ahora es hora de entrar las dependencias que necesita para que este funcione completamente.

Dependencias

Como vimos cada componente tiene un nombre y con base en la enumeración podemos ingresar en una tabla cuál es el nombre y su invocación

De esta forma tenemos conocimiento de qué tipo de invocación y una breve descripción de lo que hace cada servicio que necesita nuestro componente implementado

Descripción de conectores

Es necesario especificar el tipo de comunicaciones, es decir, ¿conocemos el formato?, ¿será por REST API o GraphQL?, ¿es síncrono o asíncrono?, ¿qué archivos envío a un storage o un S3?

De esta manera podemos identificar que tipo de formato es que está invocando, no recomendaría añadir afuera del diagrama debido a que sobrecargaría el diagrama. En caso de que exista dos tipos de llamados a un mismo componente, este tendría que añadirse y seguir la enumeración correspondiente.

Ejecución de Jobs o tareas programadas

Puede que la aplicación realice tareas programadas que sean ejecutadas en horas especificas, por ello es necesario especificar algunos puntos, la mayoría lo tiene sea con Java con el framework Spring Batch, con python o con clokwerk si nos vamos por Rust.

La tabla anterior muestra datos simples y sencillos para saber de manera práctica que tareas ejecuta. Pueden añadirse los que sean necesarios siempre que cumpla con Tarea programa, y recordar que no es una tarea automatizada, a pasado casos de confusió con ese tema.

Rutas de servicios

Este punto es el más sencillo, simplemente es la generación del swagger o la definición del contrato de servicios, especificación de servicios expuestos, en algunos casos durante el proceso de CI/CD se genera la especificación OpenAPI para que APIS Managemento APIS SaaS, puedan exponerlos, asi como documentarlas

Historial de cambios

Esta parte final y muy reconcida como el changelog, nuevamente traemos el concepto de CI/CD, al utilizar SemVer o Calver, este debería estar añadido para saber cuales fueron los cambios por cada versión que arroje CI/CD

• Versión 1.0.0:

  • version inicial

  • Se Añadieron Rest WebClient

  • Se Añadieron validadores

Agradeceré mucho sus comentarios y feedbacks

Enlace de descarga de plantilla Markdown y DrawIo:

https://filebin.net/qmw2pz9ihha0yi8t/documentation.zip (904cc2c982f6353ec7f6c7283208e68e)
Comprobación de antivirus:
https://www.virustotal.com/gui/file/ffecff2bee4652eccbd894e0b6d43a98990d96956eaa3772c19cbf0f4604d331?nocache=1