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