Markdown & PlantUML
Herramientas de documentación para developers prácticos
Una de las tareas más comunes de un developer aparte de hacer código bien hecho, es documentar lo que hacemos. Y si eres como yo, crees que de verdad vale la pena hacerlo por muchas razones, pero no quieres gastar el mismo o mas tiempo documentando que codificando, es por eso que hoy les hablaré de una lenguaje de marcado y una tool para hacer UML que combinadas logran hacer el trabajo de documentación mas simple para nosotros.
Documentar es una tarea común en nuestro día a día, documentamos el diseño de nuestro código, cuál es su estructura, en qué parte de un sistema se inserta o si es un sistema aislado, con qué componentes se comunica y/o relaciona, cuáles son sus casos de uso, requerimientos y muchas cosas mas. Documentamos código para hacerlo mas claro si por alguna razón nuestro código no se explica a sí mismo, o si es necesario dar más información para los que harán uso de él, como es el caso de las APIs, web services, etc., pero sobre todo, documentamos porque es necesario dar a conocer lo que hacemos, cómo lo hacemos y por qué lo hacemos de esa forma, de lo contrario otras personas que tengan acceso a nuestro código se pueden perder sin una guía clara. No podemos pensar que somos únicos en el desarrollo de una aplicación o sistema, o que el resto de las personas piensan como nosotros, es por eso que documentar nos puede ayudar a trabajar de forma colaborativa e incrementar nuestra eficiencia y nuestro desempeño en el equipo.
Documentar en general, es una buena práctica. Pero no debemos hacer esta tarea una carga, ni debe ser una tarea que consuma la mitad de nuestro tiempo de desarrollo, desarrollar es nuestra tarea principal, y documentar una tarea complementaria.
Actualmente existen en el mercado muchísimas herramientas para hacer documentación de desarrollo de software, herramientas tan simples o tan robustas que sin duda nos pueden ayudar a hacerlo, pero ¿por qué usar Markdown & PlantUML?
Markdown
Es un lenguaje de marcado ligero, una forma sencilla de formatear texto para que se vea bien en cualquier dispositivo [1]. Fue creado por John Gruber en el 2004 en colaboración con Aaron Swartz en la sintaxis [2]. Ellos vislumbraron una forma sencilla de escribir y leer texto plano para las personas, con símbolos de teclado que ya conocemos, marcando sólo lo esencial sin lograr cosas como cambiar el color, tamaño o tipo de letra.
Si lo vemos desde un punto de vista práctico, documentar nos lleva a la generación de contenido, no a la forma en como se ve la letra o el color de nuestro contenido, siendo pues tan prácticos como podamos, Markdown es nuestra solución simple y rápida de generar contenido.
Usando Markdown para documentar podemos encontrar que para hacer que una palabra o frase se vea en negrita sólo necesitamos agregar dos asteriscos o dos guiones bajos (** o __) al inicio y al final de la palabra o frase y para que se muestre en cursivas sólo basta un asterisco o guión bajo al inicio y al final. Si deseamos poner encabezados, títulos, subtítulos, podemos hacer uso del símbolo de gato (#) al inicio de nuestra frase. Ejemplo:
# Este es mi título## Este es mi subtítuloEste es una ejemplo de cómo usar **Markdown** para generar nuestro _contenido_.
NOTA: tu archivo debe tener extensión *.md
De esta forma es como vamos a escribir o redactar cuando usemos Markdown, usando símbolos para darle formato a nuestro texto plano, en pocas palabras: texto plano para dar formato a texto plano. Pero ¿cómo se ve el formato de mi texto plano?
Como podemos ver en la imagen anterior, el símbolo de # dio formato de encabezado, usando ## dos gatos hicimos un subtítulo, de la misma forma que se haría con los tags de HTML <h1>, <h2>, en ese mismo formato y tamaño. Los dos asteriscos ** al inicio y fin de nuestra palabra dieron formato de negrita y los guiones bajos dieron formato de cursiva. Si te pudiste dar cuenta el texto plano que escribimos usando Markdown se debe convertir a algún formato, lo que da mucha flexibilidad, ya que usando el mismo estilo de escritura podemos hacer que se convierta distintos formatos siendo HTML el más común y mas usado, por ejemplo Github es una de las empresas que ha implementado Markdown para su servicio, la documentación que se hace en Github utiliza Markdown. Otros proyectos que lo usan son: Hugo un framework para crear páginas mayormente estáticas, la mayoría de los servicios de Blogging y algunos editores de texto que comúnmente usamos para desarrollo de software como: atom, visual studio code, sublimeText, etc. En estos editores por lo general ya viene instalado, pero si por algo no lo está, es tan fácil como instalar el plugin de Markdown y listo.
Actualmente Markdown se está estandarizando, un grupo de personas se dio a la tarea de hacer una especificación de este lenguaje de marcado para que sea mas fácil su implementación. Si quieres saber más sobre su especificación lee y aprende Markdown aquí. Además, aquí una guía rápida que siempre tengo a la mano.
Documentar se volverá más fácil si sólo pensamos en escribir símbolos para dar formato a nuestro contenido, sin pensar tanto en que se vea bonito, y pensando mas en darle estructura para que sea mas legible. Es por eso que Markdown es un lenguaje al que le debes dar una oportunidad.
PlantUML
Es una herramienta de código abierto que permite a los usuarios crear diagramas UML a partir de un lenguaje de texto plano, y esta herramienta utiliza el software Graphviz para diseñar sus diagramas [3]. Sí, mas texto plano para dar formato :)
A diferencia de muchas otras herramientas de creación de diagramas UML ya sea online o en aplicaciones, PlantUML es en mi opinión la más sencilla que he usado, la que me ha permitido crear un diagrama completo en 5 minutos aproximadamente y que inclusive lo he podido usar en una junta de diseño de software en mi trabajo para proyectar el diseño que estamos discutiendo de forma dinámica. Es fácil de instalar, rápido de aprender y todos los diagramas que hagas son exportables a imágenes, pdf, html, etc.
Tiene algunas desventajas comparada con otras herramientas y es que el “convertidor” que diseña los diagramas define el acomodo de los componentes, las conexiones etc., y eso puede o no gustarte dependiendo de si tu diagrama es muy grande y el acomodo confunde el flujo que debe llevar o de si te importa mucho la estética. Otra cosa es que estéticamente no es muy bonito, pero cumple con su función principal que es diagramar UML. Ejemplo:
@startuml
start
if (condition A) then (yes)
:Text 1;
elseif (condition B) then (yes)
:Text 2;
stop
elseif (condition C) then (yes)
:Text 3;
elseif (condition D) then (yes)
:Text 4;
else (nothing)
:Text else;
endif
stop
@endumlCon este simple ejemplo de un diagrama de actividades podemos darnos cuenta de lo simple que es escribir usando la simbología de PlantUML. Con @startuml y @enduml iniciamos y terminamos un diagrama, todo lo que está dentro se tomará en cuenta. En un diagrama de actividades tenemos un punto de inicio y uno de fin, las palabras start y stop definen estos puntos, lo siguiente es un estilo de pseudo código que agrega condiciones if , elseif , else y endif para introducir un flujo de posibles caminos. A continuación el diagrama convertido usando el pluguin de PlatUML en Visual Studio Code.
Hacer este diagrama no toma más de 5 minutos y con el plugin adecuando en nuestro editor de texto favorito hacerlo día a día para diseñar nuestro software y documentarlo no nos debe costar más de lo que desarrollamos.
Te he presentado 2 formateadores de texto plano que hacen de tu documentación algo muy sencillo, y que si los implementas para que sean usados de forma colaborativa en tu equipo les puede dar un excelente resultado. Inténtalo, dales una oportunidad y si te gusta comienza a usarlo en tus proyectos personales y tal vez después en tu trabajo, si lo logras convence a tu equipo de usarlo también.
No me pagan por hacer propaganda de estas tools 😜 eso lo hago por amor al Open Source.
