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.
| Refutación | Respuesta |
| ¡Te equivocas!, UML 2.5 puede representar en diagramas de clases, componente, secuencia, no solo eso, sino que existe Diagrams As A Code (DaaC) como mermaid, plantuml que me permite realizar los diagramas. | Exacto, eso es lo que hace, pero ¿la colocarás en un readme.md de fácil acceso?, ¿sabes cuantos diagramas pueden ser los suficientes?, ¿todos conocen UML? |
| Utilizo el modelo C4, en el nivel 3: diagrama de componentes especifica las conexiones que tendrán entre componentes así como el tipo de invocación, si necesito detallar se utiliza el nivel 4: diagrama de clases para ver a nivel de implementación. | Es correcto, pero lamentablemente se tiende a ser muy genérico o muy específico en la descripción de las conexiones entre componentes en el nivel 3 y en el nivel 4 en algunos casos se realiza el diagrama de todos los repositorios (repository pattern / active record/ etc) o se generan todas las clases perdiendo claridad. |
| Mi empresa o personalmente tenemos un modelo propio y no necesitamos cambiar nada, todo está inventariado, conocemos que debe todo lo que debe hacerse mediante la arquitectura de solución/software, poseemos un diagrama de componentes y el contrato o Swagger nos indica que servicios o APIS dispone el componente. | Existen empresas donde tienen una gran madurez con respecto a su proceso de documentación, es muy difícil cambiar debido a que tienen un riguroso proceso de hacer/pensar/contrastar, en este punto invito a dar una lectura y contribuir para mejorar. |
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
| Componente | Tipo de invocación | Descripción |
| Email validator | HTTP | Valida correos electrónicos |
| PostgreSQL | JDBC/R2DBC | Guarda correos validados |
| payment-verify | XML | Extra un XML para verificar correos que realizaron pagos |
| Pub/Sub | HTTP/2 | Envía correos que realizaron pago |
| SQS | HTTPS | Envía correos que realizaron pago |
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?
| Conector | Formato | Tipo |
| CNT-001 | JSON | Síncrono |
| CNT-002 | JDBC/R2DBC | Síncrono |
| CNT-003 | GraphQL | Síncrono |
| CNT-004 | Protobuf/JSON | Asíncrono |
| CNT-005 | JSON | Asíncrono |
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.
| ID Job | Nombre | Frecuencia | Descripción | Dependencias |
| JOB-001 | Tarea programa de envio de verificación de pagos | Todos los días a las: 9:00 AM y a las 9:00 PM | Envia bloques de información para realizar pagos | Correo de suscriptores |
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
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
![[Quarkus] - Entendiendo el @Nonblocking (BabySteps)](/_next/image?url=https%3A%2F%2Fcdn.hashnode.com%2Fres%2Fhashnode%2Fimage%2Fstock%2Funsplash%2FjM7nOw748Ho%2Fupload%2F235aec0da3879c41d9aa08fdde5cbb2d.jpeg&w=3840&q=75)
![[Ubuntu] 24.04 - Instalación VPN FortiClient](/_next/image?url=https%3A%2F%2Fcdn.hashnode.com%2Fres%2Fhashnode%2Fimage%2Fstock%2Funsplash%2Fa_PDPUPuNZ8%2Fupload%2F1491f93ea77059db4fbe85fd714abe72.jpeg&w=3840&q=75)
![[Ubuntu] - Instalación Zoom sin extensiones (ibus)](/_next/image?url=https%3A%2F%2Fcdn.hashnode.com%2Fres%2Fhashnode%2Fimage%2Fstock%2Funsplash%2FEh1xd5xDE-s%2Fupload%2F654d53fe3407e98e8c68a7c3798ae4f3.jpeg&w=3840&q=75)