The Cathedral and the Bazaar

The shift towards agile software development models, with continuous integration processes and publication of new features, forces us as technical writers to review our own working methods. Leaving behind the model imposed by the traditional CMS and integrating documentation tasks into the development cycle is now more necessary than ever.

The Cathedral and the Bazaar

In 1999, Eric S. Raymond, one of the leading representatives of the open source initiative, published his essay entitled The Cathedral and the Bazaar. In this popular essay, Raymond writes about his experiences during the development of open code software, at the same time as he encourages programmers and companies to embrace this work philosophy.

Raymond uses the concepts of cathedral and bazaar to exemplify two quite distinct development models. The cathedral represents the development of proprietary software, where the source code is only accessible to a small group of programmers. The bazaar, on the other hand, represents the development of open source software, where the code is accessible to collaborators. The rigidity of a cathedral stands as a metaphor for a closed, centralized system, whereas the dynamism of a bazaar represents an open, collaborative system. Raymond maintains that the possibility of incorporating improvements and eliminating errors is much more extensive in a collaborative model than in a centralized one. The conclusion is that the software resulting from a collaborative model has fewer errors and is necessarily of higher quality.


The thesis explored in The Cathedral and the Bazaar has given rise to lots of discussions among those defending and criticizing open source software. The collaborative model is not free from problems, but offers advantages that make it attractive to many software development companies. It is not unusual to see such companies looking nowadays for formulas enabling them to adopt their own open source methodologies without renouncing their control of the code and intellectual property over the same.

In parallel, software development tools are incorporating more and more features that enable the principles of collaborative development to be extended to teams of workers. Together with this, the process of continuous integration and continuous delivery (known by the initials CI/CD) enables new features to be rolled out and errors to be resolved relatively quickly. Suffice to think just about the frequency with which many of the apps on our mobile telephones are updated.

The problem with content management systems

It is strange to see how this change in development methodologies has had scant repercussion on software documentation. This field continues to be founded on tasks of drafting, review, and publication that, in essence, have changed little in recent years. For writing, XML is still the standard markup language. More often than not, reviewing is still done using PDF files or, even worse, over email. And publication, which has gradually shifted to the web, often requires hours of adjustments to generate the correct PDF or HTML file.

This workflow is today sustained by complex Content Management Systems (CMS) that aim to solve the documentation needs of many different organizations at one fell swoop, but end up not entirely solving the needs of any of them.


But the fundamental problem lies in the fact that a traditional CMS understands the drafting, review, and publication tasks as actions that follow each other in orderly fashion over time and not, as so often seen in experience, all at the same time. An added problem is that the possibility of incorporating improvements from collaborators is limited to the review phase, with the documentation effectively ring-fenced for most of its development cycle.

“Ditch your CMS”

In 2014, Patrick Arlt (@patrickarlt), in the context of the Write the Docs conferences, gave a presentation titled Ditch Your CMS With Git and Static Site Generators. In this presentation, Arlt advocates abandoning the use of content management systems in favour of open code tools that favour collaboration and reduce the complexity oy documentation project.

A year later, in April, 2015, Anne Gentle (@annegentle) described the documentation process adopted by the OpenStack software manufacturer in her article entitled Git and GitHub for open source documentation. The model proposed by Gentle (subsequently developed in greater detail in her book Docs like code) proposes that technical writers should work alongside the development teams, adopting their same tools and methodologies. Because, if a software’s documentation is an integral part of the product and is produced in parallel, isn’t it more consistent to use the same workflows? In this new paradigm, writing documentation is not that different from writing code.

In summary, the Docs like Code methodology proposes:

  • Ditching the use of traditional CMS systems in favour of collaborative tools like GitHub (a code repository very popular with developers).
  • Adopting lightweight markup languages, abandoning complex languages like XML. The best-known example of these languages is Markdown.
  • Incorporating continuous review processes where reviewers can record changes at any time using pull-request mechanisms offered by GitHub.
  • Publishing product documentation regularly through the use of static page generators that enable the texts in Markdown format to be transformed into HTML code.

GitHub

Millions of developers all over the world use GitHub as the repository for their application code. But what makes GitHub such an attractive environment for amateur coders, independent developers and companies? The commercial success of GitHub has been born out of its ability to simplify the use of the Git tool (a software utility originally created to manage the development of Linux) in an easy-to-use web interface. In addition, GitHub facilitates the collaboration of multiple people on the same project in a relatively straightforward way. The complexity and scalability needs of modern software have made this feature essential.

Yet this change in software development methods is not so far away from what is happening in the documentation arena. While a manual was the responsibility of a single technical writer in the past, nowadays, with growing technological complexity and the constant integration of changes, the final result requires collaboration and co-ordination involving multiple individuals. The cathedral model imposed by content management systems has not been able to respond to this change.

The time has come

Far from being a mere concept, Docs like Code is also a reality for software companies as important as Microsoft, Amazon, or Twitter. In May, 2016, Jeff Sandquist (@jeffsandannounced Microsoft’s new documentation platform docs.microsoft.com in the following terms:
All documentation is designed to allow community contributions. Every article has an Edit button that takes you to the source Markdown file in GitHub where you can easily submit a pull request to fix or improve content.
A large part of the manufacturer’s documentation is already located on this new documentation platform in a clear wager in favour of the adoption of open systems. Other companies such as Amazon have followed this trend and it is now possible to see an “Edit on GitHub” button on many of the articles intended for developers.



In an article on the I’d Rather Be Writing blog, the specialist in documentation and technical writer Tom Johnson wrote a comment that goes to the root of the problem of using CMS:

No more black boxes that handle your content. No more expensive, proprietary systems to submit to. No more impossible-to-adjust-outputs. You can integrate it all simply, easily, and inexpensively.

The enormous influence these companies have in the world of software will, sooner or later, bring about the adoption of open bazaar-type documentation models to the detriment of rigid cathedral-type models. If effective and agile software development is the result of a collaborative process of continuous integration and publication, then documentation projects must necessarily adapt to this new reality.

(This article was originally published in Spanish and translated into English)

¿Es LinkedIn prescindible?

“Hay mucho talento fuera de LinkedIn”. Así resumía mi buen amigo José Manuel su experiencia con esta plataforma para profesionales en una conversación reciente. Esta afirmación no pasaría de un simple comentario si no fuera porque muchos -entre los que me incluyo- encontramos cada vez menos razones para participar en esta red.

Misión frente a realidad

LinkedIn, con más de 500 millones de usuarios, se define en su página Sobre nosotros como “la mayor red profesional del mundo”. Junto a esta afirmación, podemos leer:
Nuestra misión es sencilla: conectar a los profesionales del mundo para ayudarles a aumentar su productividad y rendimiento. Al unirte a LinkedIn obtienes acceso a personas, empleos, noticias, actualizaciones e información que te ayudará a destacar en tu campo profesional.
Pero basta un simple vistazo a esta plataforma para comprobar que la realidad dista mucho de esta noble misión. Y es que lejos de ser una red profesional, LinkedIn se ha convertido en una red social más. El problema fundamental es que en esa socialización LinkedIn está dejando de ser relevante para su masa de usuarios. Estas son solo algunas de las razones que ponen en evidencia la pérdida de valor del portal:

Las conexiones son irrelevantes. Las sugerencias de contactos se basan fundamentalmente en personas de nuestra propia empresa o de empresas en las que hemos trabajado anteriormente, pero resulta mucho más difícil encontrar contactos de nuestra profesión en otras empresas (algo sin duda mucho más interesante). Ocurre además que tras establecer una conexión de interés, rara vez se produce un intercambio de experiencias o ideas, precisamente porque la plataforma no ofrece ningún medio para ello. ¿El resultado? un simple engorde del número de conexiones sin ninguna utilidad real.

El sector tecnológico lo es todo. LinkedIn se ha posicionado claramente como una red para profesionales de IT. La explicación es sencilla si tenemos en cuenta el nuevo auge del sector tecnológico, con una demanda cada vez mayor de desarrolladores. Este factor se traduce en un número creciente de visitas (en otras palabras, impactos publicitarios) a contenidos y ofertas de este sector, relegando a un segundo plano al resto de contenidos.

Sin conexiones las publicaciones no tienen repercusión. LinkedIn da relevancia a los artículos y publicaciones de aquellas personas con mayor número de conexiones. Este hecho resulta obvio, pero tiene como consecuencia una pérdida del diferencial profesional de la red. La razón es que muchos usuarios buscan establecer conexiones con el único objetivo de incrementar el impacto de sus publicaciones, echando por tierra el valor profesional de estas conexiones, y de la plataforma en general.

El contenido de valor es casi inexistente. Si dejamos de lado las frases inspiradoras y célebres -repetidas hasta la saciedad-, los enlaces de autobombo, o las noticias que pueden encontrarse en cualquier otro sitio, los artículos jugosos o las actualizaciones que merecen la pena son casi inexistentes.

Instagramificación de la plataforma. En un intento por atraer un público más joven, LinkedIn ha introducido recientemente cambios que pretenden hacer más social su uso. El nuevo diseño, la aparición de las actualizaciones de estado, la incorporación de vídeo en directo o la ventana persistente de chat son muestras de ello. Pero es dudoso que LinkedIn consiga con esta estrategia atraer a un público más joven sin alienar su base existente de usuarios.


Titulitis y postureo. Estos son solo algunos de los títulos que podemos encontrar en esta red: Digital Transformer, Motivational Coach, Inno-Líder, Profesional 360°, Líder coach, Impulsor del bienestar integral, Über Tech Lead, etc.

Es difícil expresar la vergüenza ajena que provoca ver estos títulos en personas que -estoy seguro- son perfectamente válidas para realizar su trabajo, pero que no han dudado ni un instante en sumarse a la espiral de titulitis que inunda esta red. Lamentablemente, esta competición por el título más original esconde en no pocos casos la inseguridad de quien lo usa. Tampoco podemos pasar por alto el postureo de mostrar en el perfil un largo listado de grupos en los que jamás hemos hecho una aportación.

Me ahorro aquí muchas otras razones por las que pienso que el beneficio que se obtiene de LinkedIn es muy cuestionable, como el valor nulo de los endorsements, o una configuración de las opciones de privacidad intencionadamente abierta y confusa que consigue justo lo contrario: la falta de privacidad.

Peligros

Pero si LinkedIn fuese solo eso, una red social más, no pasaría de un entretenimiento inocuo. Lejos de ser así, nuestra presencia (activa o pasiva) conlleva ciertos riesgos:

Privacidad. Exponemos una gran cantidad de información personal, sin que quede claro quién es el destinatario de esta información y qué uso se hace de ella. La sentencia resuelta recientemente por un tribunal de EE.UU. a favor de una empresa que comercia con nuestros datos en LinkedIn, pone en evidencia este peligro.

Sexismo. Las actitudes sexistas contra las mujeres dentro de la plataforma se están convirtiendo en habituales, y no son pocas las que reciben solicitudes de contacto con fines no profesionales. La orientación de este portal hacia el sector tecnológico (donde los hombres son una abundante mayoría) solo puede acrecentar este problema. Los últimos cambios en la red, con un giro evidente a lo social, no parecen ser la forma más adecuada de atajar un sexismo rampante.

Distracción. Las alertas sobre visitas a nuestro perfil, las actualizaciones de nuestra red de contactos y un largo etcétera de notificaciones, disminuyen nuestra capacidad de atención y concentración. Y lo que es peor, ponen en peligro nuestro propio desarrollo profesional. Como indica Carl Newport (autor de títulos como So good they can’t ignore you o Deep work) “el valor en la nueva Economía no está en nuestro número de seguidores o likes, sino en la capacidad para enfocarnos intensamente en nuestro trabajo y ofrecer un valor único”.

“¿Qué hacen los cazatalentos en LinkedIn?”

Una vez más, José Manuel daba en la diana con esta pregunta durante nuestra conversación. Y es que si el valor de la plataforma es dudoso para los candidatos, resulta aún más difícil entender qué hace un cazatalentos en LinkedIn. Antes de LinkedIn y la popularización de las redes sociales, estos profesionales creaban una base de datos de perfiles. El cazatalentos funcionaba así como un curator de los candidatos más adecuados para las distintas ofertas de cada cliente, alimentando su base de datos con nuevos candidatos y manteniendo reuniones para conocer mejor las inquietudes profesionales y objetivos de los mismos.

LinkedIn se ha convertido hoy esa base de datos, y las reuniones han dado paso al envío indiscriminado de mensajes desde las cuentas Premium de la plataforma. El listado casi infinito de posibles candidatos y la facilidad para contactar con ellos hacen de LinkedIn la solución más lógica. Pero si todo se reduce a dar de alta una cuenta Premium y usar las capacidades avanzadas de búsqueda y envío de mensajes, ¿para qué necesito contratar a una empresa de cazatalentos? ¿Cuál es el valor añadido? Bajo este nuevo paradigma, el cazatalentos ha pasado a convertirse en un intermediario, y si hay algo nos ha enseñado internet es que los intermediarios son prescindibles y quien sobrevive es quien aporta un valor añadido.

Maury Hanigan (@rethinkhiring), en su artículo How LinkedIn Fundamentally Ruined Recruitmentexplica en más detalle esta situación y apunta:

Lo que falta en la contratación en la era de LinkedIn es la conexión personal. Fue la profunda comprensión de los candidatos lo que hizo a los cazatalentos tan exitosos.

¿Qué hago yo en LinkedIn?

La mayoría de nosotros pensamos que mantener nuestra red activa nos deparará, más tarde o más temprano, el trabajo o proyecto soñado. Pero las posibilidades de que esto ocurra son extremadamente remotas. Si echo la vista atrás, me doy cuenta de que los cambios que han marcado mi carrera profesional han sido siempre fruto de una interacción en la vida real con otras personas. Los conocidos (o conocidos de conocidos) son casi siempre las casualidades que nos llevan a nuestro siguiente empleo o proyecto. No creo que LinkedIn sea una herramienta inútil, pero sí estoy convencido de que es un medio al que otorgamos mucha más importancia y tiempo del que merece.

Volviendo a la pregunta que abre este artículo, ¿es LinkedIn prescindible? Mi conclusión es que no es imprescindible. Si buscamos en Google una persona o empresa, es muy probable que uno de los primeros resultados sea un enlace a LinkedIn. Si estoy en una situación de búsqueda de empleo o pretendo dar a conocer mi empresa al mundo, desaprovechar el posicionamiento de esta plataforma en los motores de búsqueda carece de sentido. En cualquier otra circunstancia creo que su utilidad es muy limitada.

¿Puede LinkedIn convertirse en una red profesional verdaderamente útil? No pondría mis esperanzas en ello. Los cambios incorporados recientemente a la plataforma están claramente dirigidos a los millennials, que no parecen encontrar razones para crear o mantener un perfil en esta red. Es probable que estos cambios se traduzcan en una mayor cuota de usuarios a medio plazo, pero sin duda convertirán a LinkedIn un servicio aún más irrelevante. Los usuarios de mi generación (+40) ven cada vez menos sentido en este posicionamiento hacia lo social, y los más jóvenes necesitan establecer conexiones reales que les permitan acceder al mundo laboral y progresar en su carrera, no una mala copia de Facebook.

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.