A lo largo de este artículo voy a intentar exponer mi visión, creo que compartida por muchos, sobre un área tan necesaria en el desarrollo del software como maltratada por los desarrolladores, como es la documentación del proyecto.

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, las guías, incidencias, etc.

Forget docs? – Tweet de Kelsey Hightower

[TIP] – Caso real
Un ejemplo reciente que muestra la dejadez de los profesionales del desarrollo en este tema, así como las posibles consecuencias económicas que puede acarrear, lo podemos encontrar en la demanda que ha interpuesto recientemente Hertz a un gigante del desarrollo como es Accenture. Sin entrar en la «denunciada» baja calidad del software entregado, uno de los requisitos era proporcionar unas guías en un formato interactivo y de fácil actualización (es decir, documentación) y lo que Accenture entregó fue documentos en PDF. Cuando Hertz les advirtió sobre este aspecto Accenture pidió cientos de miles de dolares para adaptarlos.

Abrazando Agile

Desde hace unos años, el proceso de construir software ha abrazado la metodología ágil así como las prácticas de despliegue continuo, de tal forma que el código generado se encuentre en producción en el menor tiempo posible.

Algunas compañías consiguen hasta cientos e incluso miles de despliegues en producción AL DÍA. Obviamente esto sólo es posible si el proceso completo se encuentra automatizado en la mayor parte de la cadena de producción.

Este ritmo de despliegue, unido a las ideas del Manifiesto Ágil sobre «código por encima de documentación» han proporcionado a los desarrolladores la excusa perfecta para dejar de lado un aspecto en la construcción del software que nunca les ha gustado, pero que es necesario, como es la documentación de lo que desarrollamos.

Así es muy común, hoy en día, encontrar proyectos donde la documentación de una nueva funcionalidad en el API no se corresponde con la última versión desplegada, manuales de usuarios con capturas de pantalla obsoletas, o diagramas de arquitectura que no se corresponden con la realidad.

En la mayoría de los casos la baja calidad en la documentación proviene, entre otras cosas, de:

• • En la planificación del sprint, la tarea de documentar lo realizado se ubica al final del mismo (en el mejor de los casos).
  • Un entorno de desarrollo «alejado» del entorno de documentación (repositorio Git vs Confluence, por ejemplo).
  • Baja o inexistente automatización en la generación de los documentos.
  • Falta de controles y revisión de lo escrito por parte del resto del equipo.
  • Justificar el trabajo realizado mediante la inclusión de pantallazos o capturas de logs enormes (la tristemente célebre, «documentación al peso»).

Situación a nuestro alrededor

Incontables son los proyectos donde la documentación se realiza utilizando editores de texto (como MS Word, OpenOffice o Google Docs por poner algunos ejemplos) con infinidad de opciones y muy especializados en la presentación (WYSIWYG). Prácticamente todos incorporan un sistema de control de cambios donde se puede ver quién modificó el qué.

Sin embargo el formato generado por estos programas suele ser un binario, con las desventajas que tiene el versionarlo junto con el código. Así mismo, para evitar modificaciones indeseadas, nunca compartimos el documento propiamente dicho sino que lo convertimos, manualmente casi siempre, a algún otro formato como PDF.

También existen otras herramientas colaborativas, como Confluence, que entre otras muchas funcionalidades disponen de un área para crear y mantener páginas para crear blogs y artículos por ejemplo. Lamentablemente, esto no soluciona ninguno de los problemas destacados anteriores, pues las páginas se alojan en un repositorio y formato propietario, alejando al equipo con un control de versiones no integrado entre otras cosas.

Comentar también el caso de algunas compañías de desarrollo con un API público (SOAP o REST por ejemplo), donde se centran todos los esfuerzos, relativos a la documentación, en tener actualizada la lista de funciones y parámetros y para ello usan herramientas tipo Swagger. En mi opinión, no consiguen mucho más que aquellos desarrolladores que siguen usando JavaDoc o similares.

Así llegamos a tener el siguiente panorama:

• • El cambio de contexto (IDE de programación vs procesador de texto) es un esfuerzo que provoca que se aborden ambos aspectos como dos tareas separadas (primero programo y después de entregar ya documentaré).
  • Lo tedioso del proceso hace que la documentación tenga que ser actualizada manualmente, con los consabidos riesgos de discrepancias entre ambos sistemas y baja calidad de la documentación.
  • No se potencia el trabajo en grupo ni se aprovechan las sinergias. Documentar es un trabajo que se delega en el recién llegado para que «así se vaya enterando del negocio».
  • Al final, tendremos una «documentación al peso» donde, para justificar el trabajo, se incluyen por ejemplo ficheros completos de logs, XML de cientos de líneas o pantallazos.

Documentación al peso

Si prestamos un poco de atención, muchas de estas situaciones pueden asociarse a la tan conocida «Deuda Técnica«, donde la elección de un desarrollo sencillo y apresurado nos hace incurrir en costes adicionales cuando queremos abordar una mejora en el producto.

De la misma manera, la elección de herramientas de uso común pero no integradas en el proyecto, así como realizar tareas manuales en lugar de buscar automatizaciones, nos generará una «Deuda Comunicativa».

Doc-as-Code

«Doc-as-Code» es una propuesta de trabajo para construir y mantener la documentación de la misma forma que lo hacemos con el software. «Doc-as-Code» va más allá e intenta abarcar todo tipo de documentación relativa al proyecto desde la concepción, arquitectura, requisitos, diseño, test, guías de usuario e incluso información sobre los despliegues.

En esta línea propone:

• • Sólo texto. Evitar el uso de editores de texto que no traten texto plano (Word, OpenOffice, etc.).
  • Versionar los documentos en un repositorio (Subversion, Git, Mercurial) junto con los fuentes.
  • Utilizar sistemas de incidencias (Issue Trackers) para que cualquiera pueda aportar o mejorarla.
  • Aplicar técnicas de Code Review para dar valor y calidad a cada aportación.
  • Automatizar e integrar la generación de la misma en el Pipeline del producto.

Los beneficios que aporta esta aproximación son:

• • Los miembros del equipo destinados a escribir la documentación se encuentran más integrados.
  • Hay una mayor implicación de los desarrolladores (suelen escribir el primer borrador y ven cómo se va enriqueciendo).
  • Aumento en la calidad de las entregas, al poder bloquear nuevas funcionalidades que no cuenten con la documentación necesaria (lo que incentivará a los desarrolladores para crear al menos ese primer borrador si no quieren ver su funcionalidad bloqueada).
  • Aumento en la cantidad de tipo de documentación al poder abarcar otras fases (detalles técnicos en despliegues como IPs, DNS, capacidades de servidores, por ejemplo).
  • Múltiples formatos de salida partiendo de un formato de entrada.

Este planteamiento no dejaría de ser una propuesta de trabajo más, si no fuera porque además, ha impulsado la creación de un valioso ecosistema de herramientas que resuelven diversos aspectos de «Doc-as-Code». En una siguiente entrega sobre Documentación continua desmenuzaremos estas herramientas que nos dejan sin excusas. Si no lo haces es porque no quieres.

Doc_as_code idratherbewriting

¿Hacia dónde vamos con esta estrategia? – Conclusiones

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 deberemos 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.

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 animaros a reflexionar sobre ello, de verdad.

Si os ha gustado esta primera aproximación hacia la «documentación continua», en la siguiente entrega incluiré además las herramientas que soportan «Doc-as-Code» y un brillante ejemplo práctico con asciidoctor (¡Spoiler!).

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!