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)

Planificar el contenido en el artículo técnico

Si en el primer artículo de esta serie se mostraba cómo dotar de estructura al documento técnico, en este segundo se describe un método para planificar su contenido. Como en cualquier otra labor con un cierto grado de complejidad, una preparación adecuada nos ahorrará tiempo durante el desarrollo del contenido e influirá positivamente en la relevancia del documento final.

Forma y función en el artículo técnico

La calidad de un artículo técnico depende de muchos factores, algunos de los cuales suelen encontrarse fuera de nuestro control. Si la herramienta de edición es excesivamente compleja o restrictiva, o si el gestor de contenidos dificulta las tareas de distribución y revisión, es poco lo que el redactor técnico puede hacer para superar estos obstáculos. Pero la calidad final del artículo depende, ante todo, de su capacidad para empatizar con la tarea el usuario y proporcionarle la información necesaria -o el acceso a otra información cuando la nuestra ya no es de interés. Y es justo aquí donde más puede aportar el redactor.

Mientras que en la entrada anterior de este blog se trataba la estructura del documento (su forma), esta se centra en el contenido (su función) o más concretamente, en la planificación de ese contenido. En documentación técnica la separación entre forma y función es puramente formal, ya que en la práctica ambos aspectos están íntimamente ligados. Vimos ya que la estructura de un documento es esencial en la búsqueda y el descubrimiento de la información por parte del usuario, pero una vez hemos captado su atención es imprescindible mostrar datos relevantes en el contexto de su tarea.

También se ha discutido la importancia de que los manuales describan tareas, y no interfaces. Debemos desterrar la idea de que la principal función de un manual es explicar minuciosamente la interfaz y opciones de un producto, dejando siempre al usuario la difícil labor de entender cómo encaja esa información en su tarea. Si hasta no hace mucho tiempo era habitual basarnos en la descripción de las pantallas y opciones para redactar un documento técnico, ahora debemos preguntarnos ¿es esto lo que el usuario necesita?

Estas descripciones -este contenido- siguen teniendo su lugar en la documentación, pero no como eje central de la misma, sino en la forma de artículos de referencia a los que el usuario pueda acceder desde la descripción de la tarea. Del mismo modo que las notas al pie y referencias de un libro nos ayudan a completar y entender mejor la historia, pero no sustituyen la historia en sí. La documentación técnica que no sustenta las acciones del usuario es, en gran medida, responsable de la mala fama que tienen los manuales entre muchos usuarios.

Etapas en la planificación de contenido

He dividido la planificación de un artículo técnico en 4 etapas, que pueden resumirse gráficamente de la siguiente forma:

Para cada etapa, se indican a continuación las herramientas recomendadas, los materiales de trabajo, el resultado esperado y las acciones correspondientes en esa fase.

Etapa 1: Analizar las tareas del usuario

Herramientas: Pizarra o software para elaborar mapas conceptuales (también llamados mapas mentales).

Materiales de trabajo: Ámbito de la tarea, especificaciones del producto, prototipos (lo que comúnmente se conoce como mockups o wireframes), entrevistas con usuarios y cualquier otra fuente de datos que podamos tomar como punto de partida.

Resultado: Mapa conceptual con análisis de tareas.

Acciones:

  • Analizamos las distintas tareas que el usuario puede completar con el software en el contexto que se quiere documentar.
  • Definimos las tareas más genéricas primero, y las más específicas después.
  • El análisis se hace sobre la base del flujo de acciones del usuario, no de las pantallas y opciones del software.
  • El foco aquí son las tareas y sus relaciones, no la jerarquía de las tareas.

Etapa 2: Definir los artículos que integran el documento

Herramientas: Pizarra o software para elaborar mapas conceptuales.

Fuentes de trabajo: Mapa conceptual con análisis de tareas (etapa 1).

Resultado: Mapa conceptual estructurado con análisis de tareas

Acciones:

  • Tomamos como referencia los 4 tipos de artículos definidos para categorizar cada una de las entradas que conforman el mapa conceptual.
  • Usamos un tipo de artículo para cada entrada.
  • Modificamos el mapa conceptual dividiendo o juntando elementos cuando sea necesario para adaptarlos a alguno de los 4 tipos.

Etapa 3: Crear la tabla de contenidos

Herramientas: Pizarra y editor de textos.

Fuentes de trabajo: Mapa conceptual estructurado (etapa 2).

Resultado: Tabla de contenidos.

Acciones:

  • Creamos una tabla de contenidos que reflejará la estructura final del documento.
  • El foco aquí es la agrupación lógica de conceptos y la jerarquía.
  • Si es preciso, cambiaremos la estructura de la tabla de contenidos durante el desarrollo del contenido (esta fase es iterativa).
  • Evitaremos exponer más allá de dos niveles en la tabla de contenidos. Es decir, nivel 1, nivel 2 y también nivel 1.1 y 1.2, pero no niveles 1.1.1, 1.1.2, etc.

Etapa 4: Desarrollar el contenido

Herramientas: Herramienta de edición o gestor de contenidos.

Fuentes de trabajo: Mapa conceptual estructurado (etapa 2) y tabla de contenidos (etapa 3).

Resultado: Borrador o documento técnico final.

Descripción:

  • Desarrollar nuevo contenido para cada artículo definido en la fase anterior.
  • Reutilizar secciones que son comunes a distintos artículos (como por ejemplo, explicar las acciones en la interfaz del usuario para abrir una aplicación o ejecutar un comando).
  • Actualizar la tabla de contenido si es necesario durante del desarrollo (esta fase es iterativa).

Durante la planificación, la tendencia es imaginar en nuestra cabeza el aspecto final del documento. Esto nos lleva a poner excesivo énfasis en la tabla de contenidos. Pero la propuesta aquí es precisamente no pensar en términos de tabla de contenidos hasta bien avanzado el análisis de las tareas. La tabla de contenidos nos limita porque solo nos permite movernos en dos dimensiones: de arriba hacia abajo, añadiendo nuevas entradas o de izquierda a derecha, añadiendo profundidad a cada entrada; pero durante el análisis inicial nuestro cerebro trabaja en múltiples direcciones, no solo en dos.

No he mencionado deliberadamente los integrantes de cada etapa porque estos dependerán del proyecto. En proyectos de gran envergadura, la colaboración de los equipos de diseño y usabilidad, analistas y desarrolladores, formadores y equipos de soporte técnico es fundamental y puede facilitarnos el análisis de las primeras etapas. En proyectos menores, como los desarrollados por el redactor técnico ocasional, es normalmente una sola persona quien lleva a cabo todo el trabajo.

El mapa conceptual como herramienta de análisis

Precisamente porque la tabla de contenidos nos limita en el desarrollo de ideas, resulta más eficaz usar mapas conceptuales en las fases iniciales de planificación. Estos mapas, ideados originalmente por Tony Buzan, son una representación gráfica de ideas que se van añadiendo -a modo de ramas de árbol- a partir de un concepto central. Cada una de estas ideas puede dividirse a su vez en otras de menor entidad, pasando así de los conceptos más generales en el centro del mapa a los más específicos en la periferia.

En nuestro caso el centro del mapa estará ocupado por el tema sobre lo que vamos a escribir (normalmente, una nueva funcionalidad del software). A partir de este elemento central vamos dibujando otros que representan las acciones que el usuario puede realizar con el software. Vemos que, a diferencia de la tabla de contenidos, el mapa conceptual se adapta mejor a la forma de pensamiento durante la fase de ideación al permitir desarrollar y enlazar elementos libremente.


Quien no haya utilizado antes los mapas mentales puede sentir la tentación de pasar por alto este sistema. Mi recomendación es no hacerlo. La conveniencia de usar este método frente a otros se encuentra ampliamente documentada, su aprendizaje es rápido y la inversión en tiempo se verá compensada con creces. Tampoco es necesaria ninguna herramienta especial, podemos usar un cuaderno, una pizarra o etiquetas adhesivas. Podemos también usar uno de los muchos programas que existen para elaborar mapas conceptuales, aunque no importa lo rica en funcionalidades que sea la aplicación de software, siempre nos limitará en mayor medida que una pizarra durante el análisis. Una vez el mapa mental está ya maduro, podemos utilizar un programa para almacenarlo digitalmente, editarlo y compartirlo.


La última entrada de esta serie tratará con mayor detalle el concepto de artículo. Veremos cómo los 4 tipos descritos (concepto, referencia, tarea y resolución de problemas) puede relacionarse entre sí para dar lugar a elementos de mayor entidad a los que llamaré meta-artículos. El meta-artículo constituye la pieza de unión entre el artículo (la forma) y la tarea del usuario (la función).