La catedral y el bazar

El cambio hacia modelos de desarrollo de software ágiles, con procesos continuos de integración y publicación de nuevas funcionalidades, nos obliga como redactores técnicos a revisar nuestros propios métodos de trabajo. Abandonar el modelo impuesto por el gestor de contenidos tradicional e integrar las tareas documentales en el ciclo de desarrollo es ahora más necesario que nunca.

La catedral y el bazar

En 1999, Eric S. Raymond -uno de los principales representantes de la iniciativa de código abierto- publicó su ensayo La Catedral y el Bazar. En este popular ensayo, Raymond relata su experiencia durante el desarrollo de software de código abierto, a la vez que anima a los programadores y empresas a adoptar esta filosofía de trabajo.

Raymond utiliza los conceptos de catedral y bazar para ejemplificar dos modelos de desarrollo bien diferenciados. La catedral representa el desarrollo de software propietario, donde el código fuente es accesible solo a un reducido grupo de programadores. Por el contrario, el bazar representa el desarrollo de software de código abierto, donde el código es accesible a colaboradores. La rigidez de una catedral sirve de metáfora de un sistema cerrado y centralizado, mientras que el dinamismo de un bazar representa un sistema abierto y colaborativo. Raymond defiende que la posibilidad de incorporar mejoras y eliminar errores es mucho más amplia en un modelo colaborativo que en uno centralizado. La conclusión es que el software resultante de un modelo colaborativo incorpora menos errores y es, necesariamente, de mayor calidad.


La tesis expuesta en La Catedral y el Bazar ha sido motivo de discusión entre defensores y detractores del software de código abierto. El modelo colaborativo no está exento de problemas, pero ofrece ventajas que lo hacen atractivo para muchas empresas de desarrollo. No resulta extraño ver cómo estas empresas buscan hoy fórmulas que les permitan adoptar metodologías propias del código abierto sin renunciar al control del código y de la propiedad intelectual del mismo.

Paralelamente, las herramientas de desarrollo de software incorporan cada vez más funcionalidades que permiten llevar los principios de desarrollo colaborativo a los equipos de trabajo. Unido a esto, el proceso de integración y entrega continua (conocido por las siglas en inglés CI/CD, o continuous integration/continuous deployment) permite publicar nuevas funcionalidades y solucionar errores con relativa rapidez. Pensemos solo en la frecuencia con la que se actualizan muchas de las apps en nuestros teléfonos móviles.

El problema con los gestores de contenido

Resulta extraño ver cómo este cambio en las metodologías de desarrollo ha tenido escasa repercusión en la documentación de software. Este campo sigue asentado en tareas de redacción, revisión y publicación que, en esencia, han cambiado poco en los últimos años. En la escritura, XML sigue siendo el lenguaje de marcado estándar. La revisión en muchos casos se realiza aún mediante archivos PDF o, lo que es peor, a través del correo electrónico. La publicación, que progresivamente ha pasado al medio web, requiere en muchos casos de horas de ajustes para generar el archivo PDF o HTML correcto.

Este flujo de trabajo está hoy sustentando por gestores de contenido (conocidos por las siglas en inglés, CMS) complejos, que pretenden resolver las necesidades documentales de muchas organizaciones a la vez, pero que terminan por no resolver enteramente las necesidades de ninguna.


Pero el problema fundamental reside en que el gestor de contenidos tradicional entiende las tareas de redacción, revisión y publicación como acciones que se suceden ordenadamente en el tiempo y no, como demuestra la experiencia, de forma conjunta. Como problema añadido, la posibilidad de incorporar mejoras por parte de los colaboradores está limitada a la fase de revisión, quedando la documentación efectivamente cerrada durante la mayor parte de su ciclo de desarrollo.

"Tira tu CMS"

En el año 2014 Patrick Arlt (@patrickarlt), en el marco de las conferencias Write the Docs, realizó la presentación Tira tu CMS (titulada originalmente Ditch Your CMS With Git and Static Site Generators). Arlt plantea en esta presentación abandonar el uso de gestores de contenido en favor de herramientas de código libre que favorecen la colaboración y reducen la complejidad del proyecto documental.

Un año después, en Abril de 2015, Anne Gentle (@annegentle), describía el proceso documental adoptado por el fabricante de software OpenStack en su artículo Git y GitHub para una documentación fuente abierta (originalmente, Git and GitHub for open source documentation). El modelo propuesto por Gentle -que posteriormente desarrollaría con más detalle en su libro Docs like code- propone al redactor técnico trabajar de manera conjunta con los equipos de desarrollo, adoptando las metodologías y herramientas de estos equipos. Porque si la documentación de un software es parte integral del producto y se realiza en paralelo, ¿no resulta más coherente que los flujos de trabajo sean los mismos? Bajo este nuevo paradigma, escribir documentación no dista mucho de escribir código.

En síntesis, la metodología Docs like Code propone:
  • Abandonar el uso de gestores de contenido tradicionales en favor de herramientas colaborativas como GitHub (un repositorio de código muy popular entre los desarrolladores).
  • Adoptar lenguajes de marca ligeros (del inglés, lightweight markup languages) como formato, abandonando lenguajes complejos como XML. El ejemplo más conocido de estos lenguajes es Markdown.
  • Incorporar procesos de revisión continuos donde los revisores puedan registrar cambios en cualquier momento mediante los mecanismos de pull-request ofrecidos por GitHub.
  • Publicar regularmente la documentación del producto mediante el uso de generadores estáticos de páginas, que permiten transformar los textos en formato Markdown en código HTML.

GitHub

Millones de desarrolladores en todo el mundo usan GitHub como repositorio para el código de sus aplicaciones. Pero, ¿qué hace de GitHub un entorno tan atractivo para los aficionados, desarrolladores independientes y empresas? El éxito comercial de GitHub nace de su capacidad de simplificar el uso de la herramienta Git (una utilidad de software creada originalmente para gestionar el desarrollo de Linux) en una interfaz web fácil de usar. GitHub facilita además que múltiples personas pueden colaborar en un mismo proyecto de manera relativamente sencilla. La complejidad y diversidad del software actual convierten en imprescindible esta capacidad de la plataforma para escalar fácilmente.

Pero este cambio en los métodos de desarrollo de software no dista mucho de lo que ocurre en el ámbito de la documentación. Si en el pasado un manual era responsabilidad de un único redactor técnico hoy en día, con la creciente complejidad tecnológica y la integración continua de cambios, el resultado final precisa de la colaboración y coordinación de múltiples personas. El modelo de catedral impuesto por los gestores de contenido no ha sido capaz de dar respuesta a este cambio.

El momento es ahora

Lejos de ser solo un concepto, Docs like Code es también una realidad para empresas de software tan importantes como Microsoft, Amazon o Twitter. En Mayo de 2016 Jeff Sandquist (@jeffsand) anunciaba la nueva plataforma documental de Microsoft docs.microsoft.com con las siguientes palabras:

Toda la documentación está diseñada para permitir contribuciones de la comunidad. Cada artículo incorporar un botón de edición que te dirige al fichero fuente de Markdown en GitHub, donde puedes crear un pull request para reportar un error o mejorar el contenido.

Una buena parte de la documentación del fabricante reside ya en esta nueva plataforma documental, en una clara apuesta por el uso de sistemas abiertos. Otras empresas como Amazon han seguido esta tendencia y hoy es posible ver el botón Editar en GitHub en muchos de los artículos destinados a desarrolladores.


El especialista en documentación y redactor técnico Tom Johnson (@tomjohnson) escribía en un artículo del blog I’d Rather Be Writing, en un comentario dirigido a la raíz del problema del uso de gestores de contenido:

No más cajas negras para gestionar tu contenido. No más sistemas caros y propietarios que mantener. No más formatos-de-salida-imposibles-de-ajustar. Puedes integrarlo todo de manera simple, fácil y barata.

La enorme influencia que estas empresas tienen en el mundo del software propiciará, más tarde o más temprano, la adopción de modelos documentales abiertos tipo bazar en detrimento de modelos rígidos tipo catedral. Si el desarrollo más efectivo y ágil del software es el resultado de un proceso colaborativo de integración y publicación continua, el proyecto documental tiene necesariamente que adaptarse a esta nueva realidad.


Forma y función del artículo técnico: el meta-artículo

En la última parte de esta serie de tres (ver entradas anteriores aquí y aquí) sobre el desarrollo del artículo técnico, se introduce el concepto de meta-artículo como elemento funcional básico de la información. El meta-artículo constituye la pieza de unión entre el artículo técnico (la forma) y la tarea del usuario (la función).

El manual de usuario “electrónico”

El paso del manual de usuario físico a la documentación web que hoy acompaña a muchos productos de software no ha estado libre de problemas. Con la popularización del ordenador personal, y años antes de la generalización de internet, los fabricantes de software comenzaron a sustituir las ediciones impresas de sus manuales por versiones electrónicas. Los ficheros de ayuda de Windows se generalizaron como la forma más efectiva y económica de hacer llegar al usuario la documentación de producto. Los primeros manuales electrónicos, con un contenido escasamente enlazado y motores de búsqueda limitados, se convertían muchas veces en una mera copia digital del manual en papel.


Estos manuales de ayuda electrónicos -a los que el comunicador técnico Mark Baker llamó acertadamente frankenbooks- incorporaban todas las limitaciones de un libro físico, pero sin aprovechar ninguna de las ventajas del nuevo medio electrónico. La tabla de contenidos -y no la búsqueda- continuaba siendo clave en el descubrimiento de información y cada entrada se fragmentaba frecuentemente en múltiples subentradas. El resultado era un manual de ayuda electrónico con tablas de contenido extensas, difíciles de manejar y donde abundaban apartados con poca información.

El salto final desde el manual electrónico hasta el manual web ha obligado a los redactores técnicos a replantear la manera de agrupar y enlazar el contenido. El cambio en los patrones de lectura y descubrimiento de la información que trajo consigo internet hacen que organizar la información en la web siguiendo el modelo de libro físico carezca de sentido. Si la tabla de contenidos había sido hasta entonces un elemento fundamental, las capacidades de búsqueda en la web junto con estos nuevos patrones de lectura (que discutimos ya en el primer artículo de esta serie) convertían a este elemento en secundario.

Escritura técnica orientada al artículo

Junto con la transformación del manual de ayuda físico en manual en formato web, uno de los avances más importantes en el desarrollo de documentación técnica ha sido el paso al modelo de documentación orientada a artículos. Si anteriormente el redactor técnico trataba al manual como un todo, la tendencia ahora es, claramente, organizar el contenido en torno a bloques discretos de información a los que llamamos artículos. La popularización de modelos de información como el propuesto por la especificación DITA han cimentado esta transformación.

A pesar de este avance, modelos como DITA siguen sin dar respuesta a cómo los artículos, entendiendo estos como bloques primarios de información, se relacionan entre sí de forma lógica para el lector. De hecho, en la teoría de la escritura orientada al artículo, la agrupación de artículos se desaconseja o se considera que va en detrimento de la capacidad de asimilar información por parte de lector (en una palabra, de su usabilidad). Tal como expone el comunicador técnico Tony Self en su artículo Desarrollo de información basada en artículo (originalmente en inglés, Topic-based Information Development):
Los cambios en los patrones de lectura y adquisición de información sugieren que los lectores ya no quieren leer en profundidad textos largos y lineales. En su lugar, la investigación sugiere que quieren leer de forma superficial, y leer sólo el mínimo que les permita realizar una tarea. Las estructuras de información basadas en artículos son más apropiadas para estos lectores impacientes.
Pero si, como definen estos modelos, cada artículo representa únicamente un tipo de información (tarea, referencia, concepto, etc.), ¿no corremos el riesgo de volver a aquellos manuales electrónicos del pasado, con múltiples entradas aisladas y difíciles de manejar? ¿No tendría más sentido agrupar funcionalmente aquellos artículos relacionados entre sí, incluso aunque pertenezcan a categorías distintas?

El hecho de que los patrones de lectura y adquisición de información hayan cambiado con la aparición de internet no está reñido con la creación de contenido de mayor longitud. Muy al contrario. De hecho, la extensión de un artículo, por sí sola, no debería ser un criterio válido para fragmentar el contenido. Muchas entradas de la Wikipedia incluyen artículos extensos, lo que como lectores no nos impide navegar por su contenido en busca de la información o dato necesarios. Sin duda, esta organización resulta mucho más útil que presentar la información en bloques discretos y discontinuos, obligando al lector a moverse de un nivel de contenido a otro, y rompiendo el patrón de lectura habitual.

Modelo A frente a modelo B

Los modelos de desarrollo de información basados en DITA, en un empeño por maximizar la capacidad de reutilizar el contenido (uno de los principales objetivos de la escritura orientada a artículos) son incapaces de dar respuesta al modo en que estos bloques se agrupan (tanto es así, que algunos autores no consideran DITA como un verdadero modelo de información).

El modelo A (ver imágen) ejemplifica el modelo propuesto por DITA. Bajo esta concepción, cada tipo de artículo se presenta como un elemento final y reutilizable de información. El modelo B, por el contrario, plantea que los distintos artículos se combinan en elementos de mayor entidad, a los que me he dado en llamar meta-artículos. Si el artículo supone el elemento constructor de la información, el meta-artículo constituye el elemento funcional.

El modelo A aconseja aislar las tareas de autoría de las de presentación. En palabras de Tony Self:
El formato y presentación son consideración posteriores a la autoría, y actividades posiblemente no realizadas por el autor técnico.
Pero, ¿es esto cierto? En mi opinión, este planteamiento ignora que la presentación del contenido (el cómo se relacionan entre sí los diferentes tipos de artículos) condiciona en gran medida el acceso a la información por parte del lector. El redactor puede y debe aislarse de elementos formales como el uso de fuentes, colores, espacios entre párrafos, etc., pero no puede ignorar la estructura final del artículo.

El decidir entre un modelo u otro dependerá de factores que, como redactores técnicos, deberemos sopesar para cada tipo de contenido y audiencia. Veamos dos casos para ilustrar esta idea. Pensemos por un momento en una aplicación ofimática como Microsoft Word. Las preguntas que un usuario de esta aplicación puede plantearse se resuelven normalmente con una breve explicación (añadir formato a una tabla, compartir un documento, insertar una ecuación, etc.). En estos casos, la información de contexto resulta innecesaria porque el objetivo del usuario es muy específico y el número de posibilidades muy reducido. Pero pensemos ahora en una caso más complejo, como puede ser la instalación y configuración de un servidor web. El técnico que se enfrenta a esta tarea requiere una información de contexto suficiente para entender aquello que va a llevar a cabo y evitar errores comunes. ¿Tiene sentido aquí separar la tarea en sí de la información de contexto? Separando ambas (por ejemplo, en dos artículos enlazados) perdemos la posibilidad no solo de atraer la atención del lector, sino también de facilitarle la información necesaria en el lugar donde se lleva a cabo su acción.

Usabilidad frente a reutilización

El problema se reduce, por tanto, a cómo presentar el contenido al usuario de una forma que sea coherente con su flujo de trabajo, y que a su vez permita reutilizar la información. DITA no cierra la posibilidad de agrupar diferente artículos, pero advierte contra los peligros de hacerlo, como podemos leer en la propia especificación de DITA 1.2:
Los artículos pueden definirse dentro de otros artículos. Sin embargo, la unión requiere un cuidado especial porque puede dar lugar a documentos complejos que son menos utilizables [en el sentido de usabilidad] y reutilizables.
Como enfatiza Mark Baker, el problema es que DITA prioriza la posibilidad de reutilizar un contenido sobre la usabilidad del mismo. El argumento de que la agrupación de los artículos hace el documento menos usable no parece sostenerse. De hecho, si nos fijamos, la usabilidad de un documento (en otras palabras, la capacidad de ese documento de aportar la información relevante para la tarea del usuario) es contraria en muchos casos a las posibilidades de reusar el contenido. Pensemos en las imágenes o los vídeos. Aunque la tendencia es ahora la de incorporar cada vez más elementos gráficos en la documentación técnica, durante mucho tiempo este contenido fue relegado por los costes de producción asociados y su escasa reutilización. Pero, ¿es este un contenido usable? ¿Da soporte a la tarea en cuestión que el usuario realiza? Claramente, la respuesta es sí. Usabilidad y capacidad de reutilización son, en muchos casos, elementos contrapuestos.

El meta-artículo da respuesta a la necesidad de desarrollar documentación que sea a la vez usable y reutilizable, y comienza a estandarizarse como la forma más adecuada de hacer llegar la información técnica al usuario, especialmente en tareas complejas como las que se llevan a cabo en los departamentos de IT.