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 desestrucutrado 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.

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)

Microsoft marca el camino a seguir en documentación técnica

El nuevo servicio documental de Microsoft es mucho más que un cambio estético en la plataforma de contenidos.

La pasada semana, Microsoft dio a conocer su nueva plataforma documental docs.microsoft.com. Este cambio, detallado en la primera entrada del blog del equipo, incluye elementos que no resultan novedosos en sí mismos, pero que sí lo son cuando se trasladan al ámbito de la documentación técnica. El aspecto de la documentación es ahora más parecido al de un blog que al del clásico documento técnico, con artículos más cortos y la incorporación de elementos como el tiempo de lectura de cada artículo, tipografías de mayor tamaño y diversas herramientas de comentario que recuerdan instantáneamente a Medium.


Las nuevas opciones de comentario y petición de cambios se añaden al clásico cuadro de sugerencias al final de cada artículo (que se mantiene). Con todas estas opciones y la posibilidad de añadir notas a cada párrafo no queda claro, sin embargo, qué respuesta pueden esperar los usuarios y cómo se integrarán las sugerencias enviadas en el documento final.

Pero la novedad más relevante no es estética. La gestión de cambios se realiza ahora desde GitHub, lo que permite solicitar revisiones del documento fuente mediante peticiones pull en la plataforma. Y todo ello aprovechando la sencillez de Markdown, lenguaje cuyo uso se está popularizando en los últimos años. Este uso de la plataforma GitHub no es nuevo -de hecho, Microsoft lo utilizaba ya en otras partes de su documentación-, pero por su generalización y la importancia de Microsoft, marca un punto de inflexión y un camino a seguir por otros fabricantes.

Jeff Sandquist, autor del artículo, señala también que los cambios incorporados no son sólo estéticos o de funcionalidad, sino también de contenido. Aunque no es mucho más lo que se dice sobre este aspecto, el comentario parece indicar que la documentación estará más orientada a la realización de tareas, algo que se puede ver ya en los artículos técnicos de Azure.

Aquellos que, de una u otra forma, trabajamos con la documentación del fabricante, hemos visto cómo se sucedían pequeños cambios en los últimos años, pero sin ninguna transformación significativa. Microsoft acomete así una transición necesaria, después de un tiempo en los que sus tres grandes áreas documentales -TechNet, MSDN y más recientemente, Azure- parecían evolucionar por caminos distintos.

El contenido de la nueva plataforma es aún escaso, pero los cambios introducidos apuntan a una documentación más adaptada a las necesidades del usuario, mejor estructurada y posiblemente con menos errores, gracias a las nuevas herramientas de comentario.


(este artículo fue publicado originalmente en LinkedIn el 11-05-2016)