docs.microsoft.com y el futuro de la documentación técnica

Si hubo un tema en el mundo de la redacción técnica que ocupó blogs y discusiones de Twitter en 2017 este fue, sin duda, Docs Like Code. Esta metodología, promovida inicialmente por Patrick Arlt (@patrickarlt) y desarrollada después por Anne Gentle (@annegentle), plantea un tratamiento de la documentación técnica con las mimas herramientas y métodos aplicados en el desarrollo de software. La atención suscitada por este nuevo planteamiento resulta llamativa en un espacio tan poco dado al cambio como el de la redacción técnica.

docs.microsoft.com

Y sin duda el ejemplo más destacado en la adopción de Docs Like Code es Microsoft, con su nueva plataforma documental docs.microsoft.com. La importancia de Microsoft no es solo cualitativa, por lo que el fabricante de Redmon representa en el ámbito tecnológico, es también cuantitativa, si tenemos en cuentas la cantidad y diversidad de documentación que desarrolla.

Tradicionalmente, la documentación técnica se ha asentado en los siguientes puntos:
  1. El desarrollo de contenido estructurado (encabezado por iniciativas como DITA).
  2. El uso de XML, como lenguaje para dar soporte a este contenido.
  3. La adopción de gestores de contenido, para su transformación y tratamiento.

docs.microsoft.com supone un cambio fundamental a este modelo -llamémoslo tradicional-, con una apuesta por artículos ligeramente estructurados, Markdown como lenguaje y GitHub como gestor de la información.

Si el paso del manual de usuario impreso al manual electrónico y de este al formato web son el resultado de sucesivos avances tecnológicos, el paso a este nuevo modelo documental solo puede explicarse por la irrupción de una nueva tecnología. Pero antes de entrar en ello, conviene repasar algunos conceptos.

Contenido estructurado

Explicar de qué hablamos cuando hablamos de contenido estructurado no es fácil. Esta dificultad radica en que “estructurado” es un concepto que ha cambiado considerablemente a lo largo del tiempo. Antes de la generalización del ordenador personal, todo contenido conforme a un cierto patrón podía considerarse como estructurado. Pensemos por ejemplo, en una receta de cocina donde, con pocas variaciones, se sigue una misma estructura: dificultad de la receta, tiempo de preparación, ingredientes y pasos.

Con la generalización del ordenador personal se presenta la necesidad de que el contenido pueda ser procesado por máquinas, con el objetivo de transformarlo e intercambiarlo más fácilmente con otras máquinas. Ya no basta con usar una sencilla plantilla de trabajo, es necesario que esta plantilla y las normas sean más rígidas, para que el contenido sea más uniforme y más fácilmente procesable por las máquinas (algoritmos, para ser más exactos).

Los escritores técnicos comenzamos así a escribir el contenido dentro de complejas plantillas, donde cada elemento (una lista, una tabla, un párrafo, una imagen, etc.) está perfectamente identificado y delimitado. El resultado es un contenido rigurosamente estructurado y que evita cualquier tipo de ambigüedad, facilitando su tratamiento y transformación por medios digitales.

XML

XML se convierte en el lenguaje de marcas que da soporte a este modelo de redacción técnica con un contenido altamente estructurado. Se dice que es un lenguaje de marcas porque emplea una serie de elementos, que diferenciamos con los símbolos < y >, para definir el contenido. Estas marcas representan la meta-información o semántica del contenido; en otras palabras, información sobre la información. Tomemos el siguiente ejemplo donde se describe una tarea usando el lenguaje XML:
Como se puede ver, la información de la tarea se mezcla con marcas que definen qué representa cada elemento, pero que hacen tremendamente difícil la lectura del texto.

Gestores de contenido

XML no fue diseñado para ser utilizado como lenguaje de escritura. Los textos escritos en XML son difíciles de leer o editar directamente. El que haya sido adoptado como lengua franca en documentación técnica se explica sólo por la necesidad de automatizar el tratamiento del contenido por máquinas.

Esta complejidad, inherente a XML, hace a su vez difícil gestionar la información escrita en este lenguaje. Como solución a este problema, hace varios años comenzó a popularizarse el uso de Gestores de Contenido (conocidos normalmente por su siglas en Inglés CMS, o Content Management Server). El gestor de contenido es, en síntesis, una base de datos en la que se almacenan y clasifican fragmentos de texto XML, y donde se automatiza el tratamiento de la información.

Hacia un nuevo modelo

Es innegable que XML, el lenguaje estructurado y los gestores de contenido han facilitado el avance de la redacción técnica, pero también lo es que este avance corre paralelo a una mayor complejidad en el tratamiento de la información. Estas tecnologías han hecho el contenido más fácil de procesar para las máquinas pero, al mismo tiempo, más difícil de procesar por las personas. La promesa de los gestores de contenido como solución a esta complejidad no siempre se ha visto cumplida. En este contexto no resulta extraño que empresas como Microsoft abandonen el modelo de gestión tradicional.

Por un lado, en docs.microsoft.com, Microsoft sustituye el uso de XML por Markdown, un lenguaje de marcas ligero cuyo uso y popularidad no ha dejado de crecer en los últimos años. La principal ventaja de Markdown es su sencillez y legibilidad. Hay que tener en cuenta que leer o escribir un texto en XML resulta muy complejo. La redacción en XML se apoya en programas especializados que ocultan las etiquetas del lenguaje, y la revisión de textos requiere su transformación a un formato intermedio (como PDF) que pueda ser interpretado por el revisor. Este hecho se traduce en numerosas horas de trabajo para transformar el fichero XML y ajustar el resultado final. No es extraño que muchos redactores técnicos tengan la sensación de trabajar más tiempo en transformar documentos que en la mejora de su contenido. La sencillez de Markdown rompe con este esquema y permite al redactor hacer un uso más eficiente de su tiempo.

Una de las principales críticas al uso de Markdown en documentación técnica es que carece de capacidades semánticas. Es decir, no podemos definir, como hacemos con las etiquetas en XML, la meta-información del contenido. La consecuencia inmediata es que no es posible trabajar de forma estructurada (en sentido estricto) con Markdown. Del mismo modo, tampoco existe la necesidad de trabajar con un gestor de contenido tradicional. Esto permite a Microsoft optar en docs.microsoft.com por una gestión simplificada del contenido, donde los ficheros se organizan en la plataforma de desarrollo GitHub siguiendo una estructura simple de carpetas, muy similar a lo que podemos encontrar en nuestro ordenador. Se diría que Microsoft da un paso atrás, al ignorar los procesos establecidos y probados en documentación técnica. Personalmente, creo que este es un paso muy calculado.

Google y la inteligencia artificial

Si buscamos imágenes del término “flor” en Google, el resultado será un enorme listado de fotos de flores. Esto no deja de ser obvio. Pero pensemos en ello por un momento. ¿Qué hace que esto sea posible?

El contenido que existe en internet no se encuentra meticulosamente clasificado con etiquetas que permiten identificarlo como una flor o como cualquier otro objeto. De hecho, es difícil imaginar un contenido más dispar y desestructurado que la web. Clasificar el contenido de internet con reglas de procesamiento estrictas resulta imposible. La única forma de enseñar a Google qué es una flor, es exponiendo este motor de búsqueda a muchas imágenes de flores, y asociando esas imágenes al término “flor”. Las máquinas han empezado así a aprender conceptos del mismo modo que nosotros: por asociación y repetición. Esto es, en síntesis, a lo que llamamos inteligencia artificial.

Durante años los seres humanos nos hemos dedicado a modelar la información para que pudiera ser fácilmente procesada por las máquinas. Pero mientras nos afanábamos en esta tarea, las máquinas han aprendido a adquirir conocimiento como humanos a mayor velocidad. El comunicador Mark Baker (@mbakeranalecta) explica de forma excepcional esta idea en su artículo Quality in Structured Writing.

La inteligencia artificial no es solo una nueva tecnología que mejora y sustituye a la anterior; es un cambio tecnológico fundamental que transformará nuestra manera de relacionarnos con las máquinas. Este es, precisamente, el salto tecnológico que permite a Microsoft el paso de un modelo de redacción técnica tradicional, al modelo Docs Like Code. Si las máquinas parecen haber desarrollado capacidades avanzadas para interpretar el contenido no estructurado que les ofrecemos, ¿qué sentido tiene seguir invirtiendo cantidades enormes de tiempo en estructurar ese contenido?

Tiendo a pensar -es una mera especulación- que Microsoft hizo este razonamiento durante el desarrollo de docs.microsoft.com. ¿Es XML un lenguaje más potente y robusto que Markdown? Sin duda. ¿Son los gestores de contenido herramientas que facilitan las tareas documentales? Absolutamente. ¿Es la escritura estructurada clave para el tratamiento eficaz de la información? Cierto. Todas estas son soluciones válidas, pero su justificación pierde fuerza cuando las máquinas comienzan a razonar como nosotros y, en ocasiones, mejor que nosotros.

Usuarios que escriben

Visto con el prisma de la Inteligencia Artificial, la adopción de un modelo documental Docs Like Code parece un paso lógico para Microsoft. Pero esta no es la única razón. Uno de los objetivos de docs.microsoft.com es hacer accesible la documentación al usuario final, permitiendo que este proponga cambios o mejoras o, incluso, que añada nuevo contenido.

Los gestores de contenido, el lenguaje estructurado y XML son herramientas especializadas que requieren de un conocimiento fuera del alcance del usuario final. En la práctica, la participación del usuario en el desarrollo de la documentación resulta imposible con el modelo tradicional. La simplicidad del modelo Docs Like Code, por contra, fomenta esta participación al simplificar todo el proceso de autoría. En palabras del comunicador y redactor técnico Tom Johnson (@tomjohnson):

No resulta práctico pedirle a las personas de la comunidad -que no son escritores técnicos y que no tienen las herramientas y conocimientos necesarios- que escriban en formatos estructurados. Tomar contribución de las masas requiere que simplifiques tu modelo de autoría. Termina convirtiéndose en una elección. O tomas la ruta de creación de contenido estructurado o tomas la ruta de la colaboración.

El crecimiento del número de artículos en docs.micrsoft.com, y la incorporación continua de mejoras, parecen indicar que Microsoft ha dado con las solución correcta. Una solución que simplifica enormemente el desarrollo y gestión de la documentación técnica, que permite al redactor centrarse en la mejora del contenido y la incorporación continua de cambios, y que ofrece al usuario final un canal de participación accesible durante todo el proceso.

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.