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.