Como ya adelanté en la primera parte de mi aproximación a la Documentación Continua, casi siempre que se aborda la tarea de mejorar e integrar la documentación dentro del proceso de construcción de software, se observa un rechazo natural por parte del equipo de trabajo, al entender que deberán aprender nuevas herramientas y lenguajes. Y en mi opinión, esta aproximación está condenada al fracaso, pues la tarea tiene que ser abordada por todo el equipo en su conjunto.

Si tienes hijos en edad escolar, igual esta música te suena … «El Libro Viajero, es un libro que nace itinerante y que se va escribiendo gracias a la colaboración de las distintas familias a las que va llegando en su incansable viaje». Funciona.

El libro viajero

Por documentación no sólo me refiero al típico manual de usuario, obsoleto siempre, sino que pretendo abarcar todo aspecto relacionado con la documentación durante toda la evolución del proyecto, desde su concepción hasta su despliegue incluyendo el README, la arquitectura, el API, guías, incidencias etc. Por eso “Doc-as-Code”, como propuesta de trabajo para construir y mantener la documentación de la misma forma que lo hacemos con el software, ha impulsado la creación de un valioso ecosistema de herramientas que resuelven diversos aspectos de la documentación continua. 

Voy a desmenuzar en esta segunda parte del artículo estas herramientas que nos dejan sin excusas. Si no lo haces es porque no quieres.

Herramientas

He señalado que «Doc-as-Code» no deja de ser una propuesta de trabajo y sobre ella, o a la par, se han ido creando herramientas que resuelven uno o varios aspectos de la misma que nos pueden ayudar en la implementación de una documentación continua. Por ejemplo:

• • Markdown es un lenguaje de marcado ligero con implementaciones en multitud de lenguajes (perl, python, java, java, ruby entre otros muchos), que permite la generación de documentos visualmente atractivos partiendo de ficheros de texto. Como problema principal destacar que al no haberse constituido como un estándar, existen muchas variantes diferentes.
  • reStructuredText al igual que el anterior es otro lenguaje de marcado, pero más definido y completo. Aunque puede ser usado en otros entornos es usado principalmente en Python.
  • Asciidoc es otro lenguaje de marcado similar a los anteriores con una sintaxis clara y orientada a la semántica. Asciidoctor es la implementación principal, desarrollada en Ruby, aunque también se encuentra para Javascript o Java, y como plugin para proyectos Maven y Gradle.

Recupera la ilusión de documentar tu proyecto con «Asciidoctor para Dev(Ops)

• • Antora está desarrollado por la misma comunidad que Asciidoctor y basado en éste, nos permite agrupar diferentes repositorios con diferentes ramas, incluso en un mismo repositorio, generando un «static site» con todos ellos integrados. Así podemos distribuir el conjunto de toda la documentación entre diferentes proyectos, equipos y ramas de código a la vez que generamos una versión con todos ellos.
  • Spring Rest Docs este proyecto de Spring es un buen ejemplo de cómo conseguir que el API Rest de un producto y la documentación «vayan de la mano», de tal forma que si nuestra documentación indica que un end-point va a necesitar X parámetros y va a recibir Y, cuando se ejecuten los test se realizará esta comprobación (a la par que se documenta la petición y la respuesta), fallando el test si no se cumple.
  • Geb es un proyecto ideal para ser usado en test de navegadores de tal forma que programáticamente iremos navegando por la aplicación a testear pudiendo rellenar formularios o comprobar condiciones sobre elementos visuales, con el añadido que podemos realizar capturas automáticas (screenshots) que podrán ser adjuntadas a nuestra documentación.
  • Generadores de blogs estáticos como JBake, Hugo, Jekyll pueden servir para crear un site de base de conocimiento, o trucos sobre cómo construir nuestros productos, un welcome para los recién incorporados o cualquier otro espacio que queramos transmitir.
  • arc42 es un conjunto de plantillas (Creative-Commons Sharealike) para describir una arquitectura software. En esta línea intenta por un lado, proporcionar una lista de documentos necesarios para describir una aquitectura, y por otro lado proporciona el cómo hacerlo. Así cubren hasta 12 puntos que todo proyecto debería contemplar como son: Definición del objetivo, Stackeholders y requisitos, Estrategia, Descomposición estática del sistema, Despliegue, Calidad, y Riesgos.
  • docToolChain es una implementación de la visión «doc-as-code» que ofrece un conjunto de tareas destinadas a integrarse con diferentes sistemas (Jira, Git, Sparx EA, Visio, Office entre otros) para producir un conjunto ordenado de documentos. Además de poder ejecutarse de forma individual puede integrarse por ejemplo en un proyecto Gradle y formar parte del pipeline de forma natural.

Partiendo de estas herramientas es muy fácil, como demuestra la gran cantidad de ejemplos y tutoriales que existen, crear nuestras propias integraciones con los sistemas con los que trabajamos (siempre que dicho sistema no sea completamente cerrado, lo cual debería plantearnos si no sería mejor migrar a otro).

Asciidoctor-to-markdown

Así podemos encontrar o desarrollar integraciones tales que:

• • Extraigan párrafos determinados de un fichero Word y lo vuelquen a Asciidoctor.
  • Recuperen los Jiras abiertos en un proyecto y los integre en nuestra documentación en cada build, en forma de tabla, listado.
  • Enlacen párrafos de la documentación mediante un link a una discusión en Confluence.

Integración documentación continua DocToolChain

Hacia una documentación continua

La tarea de mejorar e integrar la documentación dentro del proceso de construcción de software, debe involucrar a todos los miembros del equipo del proyecto. En la mayoría de los casos se espera que la documentación sea realizada por técnicos no relacionados directamente con el software (que, por ejemplo, no usan el repositorio de versiones o no forman parte del flujo de trabajo de forma directa) y a los que se les pide que realicen la automatización de cuantos más componentes mejor (requisitos, capturas de pantalla o despliegues por ejemplo).

Una propuesta de aproximación hacia una «documentación continua» debería pasar por:

• • Asegurar que todos los miembros del equipo cuentan con acceso al repositorio, y que tienen los conocimientos para realizar las típicas acciones como commits, reviews o merges.
  • Crear una integración mínima que genere un «index» y un «guide» y promover que sea editado y revisado por la mayor cantidad de miembros del equipo (tanto en el origen como el resultado final).
  • Practicarhasta tener un conocimiento básico de la sintaxis básica y ver que no se necesitan editores especiales.
  • Implicar a los desarrolladores en la integración de herramientas como las comentadas, que mejor se ajusten al proyecto, de tal forma que se vayan enriqueciendo los documentos. Aquí por ejemplo pueden trabajar para incluir salidas de los test o en capturar pantallazos y enlazarlos en el documento correcto.
  • Fomentar el «pair documenting» donde dos miembros del equipo trabajen sobre el mismo documento a la vez.
  • Igual que el código se organiza en múltiples ficheros (clases, librerías, paquetes) la documentación debe ser organizada de la misma forma en múltiples documentos (índice, capítulo, tips, glosario) obteniendo así los mismos beneficios que con el código (mejor comprensión, reutilización, evitar conflictos).

Ejemplo práctico con Asciidoctor

A modo de ejemplo voy a describir un caso hipotético donde aplicar los conceptos vistos:

En un momento dado alguien tiene una idea feliz sobre un nuevo proyecto o una nueva feature que incorporar a uno ya existente, y crea en un repositorio nuevo las slides de una presentación donde se explica la idea. Para ello NO utiliza PowerPoint o similares, sino que crea un fichero de texto plano y usando «asciidoctor-revealjs» lo puede convertir a una presentación HTML que se actualiza en cada commit (entrega).

[TIP] Al usar un texto plano se centra en el contenido y no en la presentación. Así mismo facilita la revisión por parte de otros miembros y la presentación se mantiene actualizada en cada cambio.

Una vez expuesta y aprobada la idea, se comienza a trabajar en ella. Los arquitectos software podrán expresar su visión mediante diagramas «UML» usando, por ejemplo, el plugin «PlantUML» el cual, partiendo de un texto plano, es capaz de generar la imagen correspondiente.

[WARNING] Probablemente esta propuesta se le quede corta a un arquitecto pues su herramienta de trabajo seguramente le ofrezca más funcionalidades. Lo importante es que esta permita extraer de alguna forma ese diseño bien sea a fichero de texto o a imagen de forma automatizada.

Según avancen los desarrolladores en la implementación, podrán enlazar parte de su código con la documentación con un simple «include:myfile.java[tag=metodo]», evitando que ésta se desactualice ante cambios en el código, a la vez que le ofrece un lugar visible donde poder explicar la funcionalidad implementada.

[NOTE] Poco a poco, los desarrolladores ven que esta aproximación les permite expresar mejor su trabajo que en el típico JavaDoc, además de ganar visibilidad.

Así mismo, los test de integración podrán comprobar que el API va en consonancia con la documentación y generarán pantallazos que podrán ser incluidos en el manual de usuario (por ejemplo) mediante el uso de «image::pantallazo.png[]». Con un pequeño script el equipo dispondrá de un documento actualizado e integrado con el resto de la documentación de los Issues abiertos.

[TIP] Si por ejemplo usamos Jira podemos realizar consultas Rest que nos devuelvan las issues de nuestro interés, volcarlas a una tabla en un fichero «issues.adoc» e incluir este script en nuestro pipeline.

Mediante una sencilla integración con el repositorio, al finalizar una versión del producto, podremos generar de forma automática un fichero «CHANGELOG» que muestre los cambios realizados entre versiones (usando los commits o pull request realizados).

[TIP] Existen muchos plugins, según sea nuestro entorno de trabajo, que nos permiten interactuar con el repositorio Git y poder generar así una lista de cambios que volcaremos a un fichero «CHANGELOG». En el peor de los casos, cuando no encontremos un plugin de nuestro gusto, podemos utilizar el propio Git ejecutando «git log» y extrayendo los cambios de nuestro interés.

Doc_as_code idratherbewriting

Conclusiones

A pesar de ser una pieza fundamental en todo proyecto, la documentación siempre ha sido una «piedra en el zapato» probablemente porque no somos conscientes de nuestra «deuda comunicativa» y asumimos que tiene que ser así.

Sin embargo, con una aproximación hacia la “documentación continua”, realizando mejoras continuas en cada iteración, reorganizando la estructura de los documentos, incluyendo nuevas secciones e integraciones, automatizando partes, etc… podemos conseguir que los pequeños cambios que se van haciendo en el producto se documenten con un esfuerzo sostenible.

En definitiva, nuestro objetivo tiene que ser que el equipo experimente el placer por poder comunicar los avances en su trabajo de una forma cómoda y gratificante. El premio es lo suficientemente jugoso como para (nuevamente) animaros a reflexionar sobre ello, de verdad.

Os recuerdo que en la primera parte de mi aproximación a la Documentación Continua establecemos sus bases. Si os ha gustado esta aproximación hacia la “Documentación Continua” estaré encantado de comentar con vosotros sobre los diversos enfoques que podemos tomar en nuestras implementaciones.

Nota del editor

Este artículo se basa en los trabajos sobre Doc-as-Code, cortesía de Jorge Aguilera, el mejor adalid de la Documentación Continua que conocemos. Su labor de difusión es incansable, tanto en vídeos como en sesiones presenciales y, especialmente, en su muy, muy recomendable ‘parque temático: PuraVida Software’.

¡Mil gracias Jorge y que no pare la doc-fiesta!

PuraVida Software logo