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

El manual no es un hotfix

La documentación de software es un recurso esencial para el usuario -tanto más cuanto mayor es la complejidad de ese software-, pero que el propio usuario entiende como su último recurso. Desde esta observación resulta fácil comprender por qué la solución a los errores de un producto de software tienen que darse en el propio producto y no en su documentación.

La escritura no puede solucionar el mal diseño

En su artículo Writing can’t fix bad design (La escritura no puede solucionar el mal diseño), Beth Aitman muestra el ejemplo de una puerta automática con un mecanismo de cierre tan confuso que se acompaña de instrucciones para su manejo. La autora utiliza este ejemplo para explicar por qué cuando el diseño de un producto no es acertado la solución no es explicar cómo usarlo. La solución es arreglar el diseño. Basta con prestar un poco de atención a nuestro alrededor para descubrir casos similares donde el diseño enrevesado de un objeto se intenta solucionar arrojando información al usuario. Desde parquímetros con un largo listado de instrucciones de uso hasta puertas donde nunca parece estar claro el sentido de giro, el mundo está lleno de ejemplos de mal diseño.


No solo coincido plenamente con el análisis de la autora, sino que además creo que el mismo argumento se puede trasladar fácilmente a un producto de software y a los errores que se derivan de su desarrollo. Si exceptuamos los problemas graves (por ejemplo, de seguridad) donde la velocidad para informar a los usuarios es crucial, dar solución a un problema con un producto en un documento no es una buena opción.

Y no hablamos solo de errores en el código, que afectan al funcionamiento del programa, sino también de aquellos que afectan a su uso. Porque una usabilidad mediocre quizá no nos impida continuar con nuestra tarea, pero puede dificultarnos innecesariamente la misma, como ocurre cuando la disposición de botones en una interfaz no sigue un orden lógico y nos obliga a pararnos para entender su funcionamiento. Esto es lo que en desarrollo de software se ha dado en llamar error estético -un nombre desafortunado, porque reduce la usabilidad a un aspecto puramente ornamental.

La gente lee novelas

La gente lee novelas. No lee documentación. -Mark Baker
En el momento de utilizar un programa de software por primera vez, el usuario no recurre a la documentación, sino que intenta descubrir el funcionamiento del mismo basándose en su experiencia previa con programas similares y en las indicaciones que le da la interfaz. Normalmente, el usuario solo recurre a la documentación en dos situaciones: cuando encuentra un error o cuando no es capaz de completar una tarea. Para el usuario la documentación es un recurso necesario, pero es siempre su último recurso.

Si entendemos esta idea de último recurso, no nos costará entender por qué el manual no es el lugar indicado para resolver errores de software o de diseño. Si una interfaz no es intuitiva y dificulta completar una tarea, añadir una explicación al manual es una solución, pero no satisface las necesidades del usuario y lo que es peor, disminuye su percepción sobre la calidad del producto. Cubrir las deficiencias de un programa en el manual puede parecer inicialmente una solución más rápida y económica que desarrollar un parche (hotfix), pero a la larga puede salir cara.

Por qué documentar

Si un buen diseño simplifica el uso de un software cabe preguntarse, ¿sigue siendo necesario acompañarlo de un manual? Invertir en la usabilidad de una aplicación no solo incide positivamente en su calidad final, además reduce la dependencia del usuario en el manual. Pero a partir de un determinado nivel de complejidad, consultar la documentación resulta inevitable. En aplicaciones como las que tenemos instaladas en nuestros teléfonos móviles no se espera que hagamos uso de un manual de instrucciones. Son aplicaciones sencillas que cumplen una única finalidad y donde las instrucciones se limitan a una pequeña introducción durante el primer uso o consejos (tooltips) para familiarizarnos con los controles en pantalla.


Pero en el mundo fuera de nuestros teléfonos no todo resulta tan sencillo. Pensemos por un momento en un paquete de software de ofimática o de diseño gráfico. Estas aplicaciones no solo son más complejas de usar, también más complejas de desarrollar, aumentando la posibilidad de encontrarnos con errores. Y es que todos entendemos que no es lo mismo el mecanismo de apertura de la puerta de casa que de la compuerta de un avión -la del avión es más compleja y viene acompañada de instrucciones.

En otros casos la documentación es fundamental para explicar no tanto cómo funciona una aplicación, sino cuál es el conjunto de tareas que debemos completar en ella. Una cosa es que un programa de software sea fácil de usar y nos permita realizar las tareas sin demasiadas complicaciones y otra muy distinta que entendamos qué tareas se espera que realicemos y en qué orden. La documentación tiene un papel esencial explicando procesos, y no solo interfaces

Si los fabricantes de software quieren evitar la frustración de sus usuarios es imprescindible que dediquen recursos a mejorar la usabilidad y reducir los errores. Pero cuando los errores -inevitablemente- aparecen, es necesario solucionarlos en el producto, y no en el manual. Porque el usuario no quiere leer manuales o descifrar interfaces, quiere completar su tarea.