Dentro de toda esta tendencia de «codificación total», siendo puristas, debemos considerar también a la descripción del sistema, tanto estática como dinámica. Así, debemos incluir a la documentación misma. La auto documentación de los desarrollos informáticos ha sido algo que desde hace mucho tiempo se ha venido persiguiendo. La mayoría de los programadores detesta documentar sus creaciones pero, paradójicamente, tanto a ellos mismos como a cualquier otro, la documentación del sistema le resulta indispensable, y que no se limita al desarrollo del software per se sino a todo su ciclo de vida.

Diversos enfoques, escuelas, filosofías y herramientas se han elaborado a lo largo de la historia del desarrollo de software para facilitar y mejorar la obligada elaboración de la documentación de un sistema^1-3 siendo el fin último poder hablar de una «auto documentación». Un punto mucho más complejo que requerirá una serie de entradas aparte. Por lo pronto nos enfocaremos en el «aspecto visual» de toda documentación.

Los diagramas siempre han sido parte fundamental de una descripción. «Una imagen vale más que mil palabras» dice una viejo refrán, y en la documentación técnica nunca han faltado¹. Si bien, desde hace tiempo han existido herramientas (de terceros, independientes, que trabajan con el código generado) o entornos de desarrollo integrados que permiten la elaboración de diagramas (de estados, clases, flujo, módulos, etcétera) a partir del código fuente, el diagrama no dejaba de ser una imagen (o archivo de un formato enriquecido) compatible con algún otro programa o aplicación con el que podía ser editado. La automatización en su generación es innegable pero el resultado no puede considerarse bajo la filosofía a la que hemos dedicado esta serie de entradas, no puede considerarse «como código». La edición (modificación, cambio) del diagrama requiere la modificación del código del que parte o una acción manual sobre el archivo gráfico o de formato enriquecido. Por «acción manual» nos referiremos a la manipulación de los objetos o pixeles del archivo que contiene al diagrama, usando la correspondiente herramienta con la que se borran, cambian o agregan elementos (dibujos o sus propiedades) en el diagrama. Estas acciones están acompañadas de una curva de aprendizaje en el uso de la herramienta de edición y luego de una sobrecarga de acciones y decisiones sobre con lo que ellos se elabora*.

La herramienta que permite la generación de los diagramas es la biblioteca Mermaid de código abierto en JavaScript. Fue creada por Knut Sveidqvist y lanzada por primera vez en 2016. Su popularidad se debe al contexto de Markdown, que permite una fácil integración con HTML (y presuponen un overhead menor en su procesamiento), que es dónde comenzaron a ser empleados y encontrados.

Inicialmente, la simplicidad y facilidad de uso (creación y edición) de los diagramas Mermaid permitió que fueran una opción popular para desarrolladores y escritores técnicos para representar visualmente información y procesos complejos sin necesidad de utilizar software de diagramación especializado. En una segunda instancia, el que fueran archivos de texto permite que puedan ser integrados también en la tendencia de «todo como código» y hacer uso de todo los beneficios que hemos mencionado en post previos. Y, finalmente, podemos mencionar que el código fuente de estos diagramas puede ser generado por un LLM a partir de una descripción textual (prompt).

* Quizás para muchos no sea algo de importancia pero para el autor de estas entradas seleccionar y decidir sobre color, forma, estilos, posición o tamaño (y cuanto cualquier otro elemento estético o de embellecimiento que es agregado a los programas de edición gráficos) son elementos de distracción y no siempre de valor agregado (que si el color, que la forma, la posición… en fin, elementos para que siempre haya un «pero» o punto para que el desarrollador deba gastar más tiempo en la elaboración del diagrama).

Referencias

1. Jacklyn Carrol, «The History of Technical Documentation«, medium.com, web. Published: 2019.04.26; visited: 2023.09.14. URL: https://medium.com/@Jacklyn_Lee/the-history-of-technical-documentation-ea7d42921933.
2. «Technical Documentation in Software Development: Types, Best Practices, and Tools«, altexsoft.com, web. Updated: 2023.03.29; visited: 2023.09.14. URL: https://www.altexsoft.com/blog/business/technical-documentation-in-software-development-types-best-practices-and-tools/.
3. «Software documentation«, Wikipedia, web. Consulted: 2023.09.14. URL: https://en.wikipedia.org/wiki/Software_documentation.