La proliferación de metodologías ágiles transformó muchas cosas en el mundo del desarrollo de software, incluyendo la documentación. El Manifiesto Ágil cita el problema más inmediato, y no de forma muy simpática, declarando la valorización de “software en funcionamiento más que documentación completa”. Este tramo del Manifiesto ha sido un pretexto para dejar la documentación de lado, ya que esta se configuraría más como un desperdicio de recursos que como un activo que agrega valor al producto.

Sin embargo, esa visión es falla, y es incluso desautorizada por el propio Manifiesto, que afirma que “aún con valor en los ítems a la derecha, valorizamos más los ítems a la izquierda”. O sea, la documentación tiene valor — aun cuando hablamos de metodología ágil — aunque es importante no colocar la documentación en un nivel superior al producto en funcionamiento.

Sí, la documentación gasta recursos, como cualquier actividad corporativa. Por eso, documentar demás es sí un gasto innecesario, tanto en términos de tiempo y esfuerzo personal como de espacio para mantenimiento de los archivos. Pero documentar de menos, o documentar mal, también es un desperdicio de recursos. Y eso puede reflejarse, por ejemplo, en llamados de soporte innecesarios por la falta de material de apoyo a los clientes y en más tiempo y esfuerzo en la capacitación de nuevos empleados en los equipos de desarrollo.

Es por eso que la decisión de qué, cuánto y cómo documentar debe siempre tener en consideración los riesgos y costos de documentar más o menos que lo suficiente. La cuestión principal, entonces, no es si debemos o no documentar (¡debemos!), sino cómo podemos encontrar la medida justa de una documentación que sea, como el proceso de desarrollo de productos, ágil.

Documentación de código

Yo sostengo que lo primero y fundamental para encontrar esa medida es no hacer un clivaje demasiado grande entre la documentación y el código del producto. Aun cuando nos referimos a documentos técnicos para el usuario final, como manuales y tutoriales, que son el foco principal de lo que llamo “documentación técnica” en este texto. De hecho, hay un concepto cada vez más difundido respecto a esto, el “doc as code”, que pone exactamente que la documentación sea vista y producida como código (o, como lo llamo en este texto, que tengamos una “documentación-código”).

La idea fundamental por detrás de ese concepto es que tratar textos de producto como código — incluso usando las mismas herramientas aplicadas al desarrollo de softwares — permite incluir la documentación dentro de la planificación de entrega de los productos. Esto reduce inconsistencias entre documentación y producto, facilita el mantenimiento de una documentación actualizada y evita retrabajos innecesarios.

Y esa modificación en la forma de ver documentación puede tener un impacto positivo muy significativo en la calidad del proceso de escritura y publicación de textos. Esto porque las herramientas de codificación, revisión y de versión — y también las metodologías de gestión de proyectos — que son de amplio uso en el desarrollo de softwares hacen al proceso de desarrollo de documentación más rápido, colaborativo y organizado.

Para especificar más el funcionamiento y ventajas de una documentación-código, vamos a pensar en dos dimensiones del desarrollo de documentación: la escritura de los textos y el proceso más amplio de seguimiento del ciclo de vida de cada documento, que incluye su escritura, pero también su diseño, revisiones, pruebas, publicación, mejora continua y análisis de métricas. Podemos llamar a este proceso más general como flujo de trabajo, o workflow, término generalizado en las empresas de tecnología.

Proceso de escritura

Cuando necesita escribir un texto que no tendrá que ser actualizado frecuentemente y solo necesita convertirlo a PDF una vez, el Word es realmente una excelente opción. Pero un documento técnico es, cada vez más, un organismo vivo. Este siempre necesita ser revisado y mejorado, usualmente de forma colaborativa, a medida que se suceden los cambios en los productos, y la mayor parte de las veces es publicado en sitios, no (exclusivamente) compartido como PDF. Archivos binarios, como los .doc, que son pesados, ocupan mucho espacio en disco, y necesitan procesadores de texto para ser escritos y vistos, simplemente no son la elección adecuada para la inmensa mayoría de documentos técnicos.

Tratar documentación como código significa, en primer lugar, que ella debe existir en el mismo ambiente que el código. Esto, siguiendo las prácticas más comunes, quiere decir que ella será mantenida en repositorios de código con soporte para versiones (o, más específicamente, el control de versión distribuido), como el Github y el Bitbucket. Y el formato del archivo debe ser aceptado por el servicio de repositorios, lo que nos lleva a los formatos de texto puro, que son livianos y pueden ser vistos en cualquier editor de texto.

Pero esto no quiere decir que vamos a escribir la documentación de producto en TXT y usando el bloc de notas. En cuanto al formato, hay muchos lenguajes de texto puro con sintaxis para elementos de formatos y layout. Es lo que llamamos lenguajes markup. Personalmente, soy discípula del AsciiDoc, pero usted puede preferir Markdown o RestructuredText. En cuanto a los editores de texto, hay una miríada de óptimas opciones. Yo, por ejemplo, utilizo Atom, donde puedo instalar paquetes para facilitar mi proceso de escritura. Además de realzar la sintaxis con AsciiDoc, uso una herramienta para chequear errores de ortografía y saco ventajas de la funcionalidad de búsqueda y sustitución de términos, muy superior a la que yo tendría en un procesador de texto. Por medio de expresiones regulares, encuentro y sustituyo palabras o frases rápidamente en un archivo o en un proyecto completo. La propia organización de textos en proyectos ya es un beneficio enorme. Es más fácil encontrar el texto que necesita, ya que lo ve en las carpetas de un proyecto dentro de su editor. Y como cada archivo es muy liviano, es fácil también abrir y trabajar con varios archivos al mismo tiempo, incluso compartiendo una misma pantalla.

No hay nada de nuevo aquí para los desarrolladores que escriben documentación técnica, ya que ellos ya están acostumbrados con los editores de texto para codificar, incluso si escriben la documentación en procesadores de texto. A su vez, los technical writers que no son desarrolladores pueden sufrir un poco al abandonar los procesadores WYSIWYG (“lo que usted ve es lo que usted obtiene”). Pero es fácil acostumbrarse a algo bueno, y las ventajas de la documentación-código superan, ¡y mucho!, las desventajas.

Workflow

Pero más allá de las modificaciones en el proceso de escritura del texto en sí, el aspecto que juzgo que es el principal punto fuerte de la documentación-código es la facilidad de integración de la documentación en el workflow seguido para el desarrollo de productos.

Mantener el texto en repositorios de código significa usufructuar de las herramientas no solo para versionar, sino también de seguimiento del ciclo de vida de un texto a lo largo de sus diferentes etapas de desarrollo, debidamente reflejadas en branches distintas dentro de un mismo repositorio. Con esto, es posible insertar el texto en la planificación del producto como un todo, incluyéndolo en el ámbito de la gestión del proyecto y siguiendo las mismas buenas prácticas de revisiones y pruebas antes de entrar en producción.

Como para los softwares, es posible resolver problemas en la documentación por medio de hotfixes o bugfixes, cada cual con su respectiva branch, y provisionar versiones de lanzamiento de documentación junto con las versiones de los productos. Más que eso, el texto se vuelve de hecho una entidad viva — constantemente actualizada — y es más fácil de compartir el trabajo entre un equipo, sea cuando hay más de un autor por texto, sea cuando hay un autor solo pero el proceso de revisión está descentralizado entre los distintos desarrolladores del equipo.

Con el texto integrado al producto, es más fácil también coordinar los diferentes papeles. Los technical writers quedan menos desplazados y pasan a formar parte del equipo de desarrollo. Esta integración se vuelve una vía de doble mano para la colaboración. Por un lado, los technical writers se sienten más cómodos para pedir el input de los desarrolladores para la producción del texto; por otro, ellos pueden, ocasionalmente, también contribuir para el propio producto. Esto porque ellos tienen que aprender sobre cada detalle de los productos y probarlos con el cliente final en mente. Esto puede generar insights y contribuir para la detección de bugs. Queda claro que este no es el objetivo del trabajo de un technical writer, pero no deja de ser una externalidad bienvenida.

Para concluir: lo que vale es planificar

Este texto buscó mostrar algunas de las grandes ventajas de tratar documentación como código. Solo se necesita destacar que estas ventajas no implican que todos los textos técnicos tengan que ser escritos de esta forma.

Recuerda que “ágil” no es una metodología, un proceso específico y bien definido, sino un conjunto de valores, un modo de pensar y organizar la arquitectura y el desarrollo de softwares. Ser ágil es, antes que nada, evaluar e implementar la forma más adecuada de llegar a un determinado fin gastando el mínimo de recursos posible.

Aplicando esta lógica a la documentación, no siempre el workflow que ya cité aquí será la mejor alternativa. Dependiendo de la audiencia de sus textos, de la cultura de desarrollo de su equipo de producto, de las necesidades específicas de publicación que usted tiene, usted puede llegar a conclusiones diferentes de las mías.

De todas formas, si el objetivo es escribir de forma ágil, vale repensar las prácticas de documentación. ¿Estoy documentando demasiado? ¿Estoy documentando mucho menos de lo que debería? ¿Cuál es el ciclo de vida de los textos que produzco? ¿Cuáles tipos de texto que precisamos generar y cuál es el método ideal de publicación para cada tipo? Responderse a estas preguntas es el primer paso para escribir documentación ágil. Y, después de responderlas, lo que vale es planificar el flujo de su documentación.