Documentación sin fricción

En marketing, fricción se define como la resistencia psicológica del consumidor a realizar una compra. Los consumidores queremos obtener el producto deseado, pero sin vernos obligados a un tedioso proceso para ello. Una página web poco intuitiva o una larga cola de clientes en un mostrador pueden echar atrás a un comprador inicialmente convencido. De igual forma, los usuarios buscan poder resolver sus dudas en el manejo de herramientas, pero -cada vez más- sin recurrir al manual de instrucciones.

El manual

“Los usuarios no leen documentación”. Esta afirmación, muy popular entre los redactores técnicos es, sin embargo, incompleta. Como señala el comunicador Mark Baker en su artículo Usersʼ Advocate: Nobody Reads Documentation, los usuarios no leen documentación, de la misma forma que tampoco leen recetas de cocina o diccionarios. Los usuarios consultan:

Hay una gran diferencia entre consultar una fuente de información y leerla. La lectura puede tomar horas o días. La consulta lleva minutos o segundos. La lectura requiere tiempo para la actividad de leer. La consulta tiene lugar en el contexto de otra actividad.

Pero consultar la documentación obliga, en cualquier caso, a detener la tarea que llevamos a cabo para realizar la consulta. Si la ayuda no está integrada en el producto, nos encontramos con el problema añadido de encontrarla. No resulta extraño que todos recurramos a Google o al compañero más cercano para resolver nuestras dudas. 

Pensemos por un momento en la última vez que apareció un error en el panel de nuestro electrodoméstico o el salpicadero del coche. ¿Cuál fue nuestra primera reacción? Google. Consultar internet para resolver una duda se ha convertido ya en un acto reflejo. Y si no obtenemos una respuesta satisfactoria, la mayoría de nosotros contactará con el servicio técnico. Buscar información sobre el error en el manual es siempre nuestra última opción.

Consumidores y fricción

Pero, ¿por qué ocurre esto? En marketing se habla de puntos de fricción para analizar los factores que se interponen entre el consumidor y la adquisición de un producto o servicio. La fricción puede tener un origen interno (nuestra conciencia recordándonos que no podemos permitirnos ese coche nuevo) o externo (una larga cola en el supermercado). Cuantos menos puntos de fricción, más posibilidades de compra. 

Las empresas conocen bien este hecho, y buscan eliminar -o reducir- la fricción proporcionando a los clientes la mejor experiencia de compra posible. No es casualidad que aquellas empresas que mejor entienden estos factores sean líderes en su sector. Veamos solo unos ejemplos que nos ayudarán a entender mejor este concepto:

Amazon. Mediante el uso de su botón “1-click”, Amazon elimina instantáneamente el tedioso proceso de completar nuestros detalles durante el pedido (dirección, forma de pago, método de envío, etc.). Pero Amazon va más allá en este proceso, con lo la posibilidad de pedir productos con nuestra voz usando el asistente Alexa, o usar un simple botón físico para, de manera instantánea, hacer la compra del detergente o el papel higiénico.

Apple. La calidad y la atención por el detalle y el diseño de los productos de Apple es difícil de cuestionar. Pero para muchos consumidores estos factores no justifican el alto precio que es necesario pagar para adquirir estos productos. Apple conoce este hecho, y por ello ofrece la posibilidad de ver y tocar sus productos en las diferentes tiendas físicas Apple Store repartidas por todo el mundo (unas 500 en la actualidad). Esta posibilidad, junto con una experiencia de compra cuidada y un entorno que permite experimentar libremente con el producto, reducen considerablemente la oposición inicial del comprador. 

Uber. Independientemente del dilema ético que a muchos nos supone usar Uber, el éxito de este servicio de transporte privado es innegable. En muchas capitales del mundo, Uber es ya el medio de trasporte privado por defecto. Como señala Scott Galloway (@profgalloway) en su libro “The Four”, el éxito de Uber no se debe a su sofisticado sistema de seguimiento por GPS, ni tampoco al menor coste del servicio en comparación con un taxi tradicional, sino a la facilidad de pago. El coste se carga automáticamente usando el método de pago seleccionado en la aplicación, sin que sea necesario buscar monedas y billetes apresuradamente en la oscuridad del asiento de atrás.

El momento del pago es un punto de fricción frecuente. Empresas como Uber han sabido entenderlo; otras fallan estrepitosamente. Un buen ejemplo son las compañías aéreas: ¿por qué tengo que pagar en el momento de pedir un café durante un vuelo si la compañía aérea tiene ya todos mis datos (asiento, nombre, dirección de correo electrónico, tarjeta de crédito)?

Documentación sin fricción

Los redactores técnicos podemos aprender mucho de las estrategias empleadas por estas empresas. Si la fricción es la barrera que separa a nuestros usuarios de la documentación, la solución no puede ser otra que buscar fórmulas que la hagan más accesible. Planteo aquí algunas de estas fórmulas. 

Internet

Señalar la importancia de tener la documentación en formato web en internet puede sonar fuera de lugar en 2018. Pero es sorprendente la cantidad de productos que carecen de una documentación publicada en formato accesible, como HTML. Merece la pena recordar que tener la documentación en internet no significa colgar un manual en PDF en una página web.

Internet es ya (desde hace tiempo) el medio en que todos nos movemos y nuestros teléfonos móviles, el vehículo para navegar en él. Disponer de la documentación de un producto en internet, de forma accesible, es el mínimo exigible a cualquier fabricante.

Ayuda integrada y contextual

Pero no basta con que la ayuda esté en en internet. Si el usuario ha de abandonar su medio de trabajo para consultar la documentación, estamos añadiendo un punto de fricción. En este sentido, es fundamental integrar el manual en el uso del producto. En resumen, llevar la ayuda al usuario y no al revés.

La ayuda tiene que ser, además, sensible al contexto. En otras palabras, capaz de responder a las acciones que se desarrollan en la pantalla. La ayuda contextual mostrada por herramientas como Google Sheets o Smartsheet cuando editamos una fórmula es un buen ejemplo de esto. Integración y contextualización son las claves.

Ayuda multicanal

Los redactores técnicos seguimos pensando en la documentación en términos de formato (PDF, Word, HTML, etc.) y no en términos de medio, olvidando la importancia de que la información sea accesible desde cualquier lugar donde el usuario desarrolla su tarea. Para el trabajador de una fábrica este medio puede ser un manual físico, para el empleado de oficina puede ser internet, y para la enfermera que asiste un paciente en un domicilio, el teléfono móvil.

Un ejemplo de esto lo tenemos en la cadena de cosméticos Sephora. Sephora brinda a sus clientas una experiencia de compra multicanal, donde la tienda actúa como el espacio lúdico, pero donde la posibilidad de probar, reservar y pagar el producto se puede realizar desde distintos medios: página web, aplicación para el móvil o un chatbot integrado en un programa de mensajería como Messenger.  Sephora ha sabido entender que la forma más eficaz de llegar a sus clientas es estando disponible donde ellas centran su ocio. Y ese ocio se desarrolla (cada vez más) en la pantalla de nuestro teléfono móvil.

Realidad aumentada

La realidad aumentada (conocida por las siglas en inglés AR, de Augmented Reality) no es un concepto nuevo, como tampoco lo es su aplicación en la documentación técnica. Pero esta tecnología no ha sido una realidad palpable hasta hace pocos meses. La razón es simple: la tecnología necesaria aún no estaba disponible. La novedad es que ahora esta tecnología, limitada inicialmente a entornos muy concretos y con un alto coste de producción, se ha generalizado.

Gracias a la realidad aumentada (no confundir con la realidad virtual) nuestro teléfono móvil puede reconocer los elementos del mundo real (dimensiones, distancia entre objetos, iluminación, etc.) y superponer en este objetos no reales. Un buen ejemplo de esto es la aplicación de Ikea, que nos permite probar cómo quedarían los muebles en casa.

En 2017 Apple presentó ARKit, un conjunto de herramientas mediante las cuales los desarrolladores pueden crear aplicaciones de realidad aumentada para dispositivos iOS. Pocos meses después Google hizo lo propio con ARCore, destinado al desarrollo de aplicaciones Android. Estas herramientas, junto con los teléfonos móviles de última generación, ponen esta tecnología en nuestros bolsillos.

La realidad aumentada brinda posibilidades de asistencia y formación al usuario que no habían sido posibles hasta el momento. Pensemos por un momento en la capacidad de enfocar un objeto con nuestro teléfono móvil o tableta y obtener una visualización superpuesta de la ayuda para cada una de sus partes.

Chatbots

En el artículo ¿Son los bots el futuro de la documentación? hablé ya de las posibilidades que los asistentes conversacionales (o chatbots) ofrecen para comunicar con el usuario en su propio lenguaje y medio. Estoy convencido de que los chatbots, junto con la realidad aumentada, tendrán un papel clave en la documentación de productos de software y productos físicos respectivamente.

Un buen ejemplo de la aplicación de estos dos elementos lo encontramos (de nuevo) en Sephora. Desde las aplicaciones de esta cadena de cosmética, las clientas pueden conversar con un chatbot para obtener información sobre productos, reservar una sesión de maquillaje o pedir recomendaciones acerca de los colores más apropiados para el tono de piel. Sephora brinda también la posibilidad de probar los productos directamente en la aplicación, a través de una interfaz de realidad aumentada que emplea reconocimiento facial.

Empresas como Sephora, Amazon o Uber han entendido que eliminar fricciones es la clave para facilitar el acceso a un producto o servicio. Los redactores técnicos debemos de entender los puntos de fricción generados por la documentación, y realizar la transformación necesaria. Si no lo hacemos, corremos el riesgo de que la documentación deje de ser relevante. O peor, que el usuario abandone nuestro producto en favor de otra empresa que sí ha llevado a cabo esta transformación. 

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