Forma y función del artículo técnico: el meta-artículo

En la última parte de esta serie de tres (ver entradas anteriores aquí y aquí) sobre el desarrollo del artículo técnico, se introduce el concepto de meta-artículo como elemento funcional básico de la información. El meta-artículo constituye la pieza de unión entre el artículo técnico (la forma) y la tarea del usuario (la función).

El manual de usuario “electrónico”

El paso del manual de usuario físico a la documentación web que hoy acompaña a muchos productos de software no ha estado libre de problemas. Con la popularización del ordenador personal, y años antes de la generalización de internet, los fabricantes de software comenzaron a sustituir las ediciones impresas de sus manuales por versiones electrónicas. Los ficheros de ayuda de Windows se generalizaron como la forma más efectiva y económica de hacer llegar al usuario la documentación de producto. Los primeros manuales electrónicos, con un contenido escasamente enlazado y motores de búsqueda limitados, se convertían muchas veces en una mera copia digital del manual en papel.


Estos manuales de ayuda electrónicos -a los que el comunicador técnico Mark Baker llamó acertadamente frankenbooks- incorporaban todas las limitaciones de un libro físico, pero sin aprovechar ninguna de las ventajas del nuevo medio electrónico. La tabla de contenidos -y no la búsqueda- continuaba siendo clave en el descubrimiento de información y cada entrada se fragmentaba frecuentemente en múltiples subentradas. El resultado era un manual de ayuda electrónico con tablas de contenido extensas, difíciles de manejar y donde abundaban apartados con poca información.

El salto final desde el manual electrónico hasta el manual web ha obligado a los redactores técnicos a replantear la manera de agrupar y enlazar el contenido. El cambio en los patrones de lectura y descubrimiento de la información que trajo consigo internet hacen que organizar la información en la web siguiendo el modelo de libro físico carezca de sentido. Si la tabla de contenidos había sido hasta entonces un elemento fundamental, las capacidades de búsqueda en la web junto con estos nuevos patrones de lectura (que discutimos ya en el primer artículo de esta serie) convertían a este elemento en secundario.

Escritura técnica orientada al artículo

Junto con la transformación del manual de ayuda físico en manual en formato web, uno de los avances más importantes en el desarrollo de documentación técnica ha sido el paso al modelo de documentación orientada a artículos. Si anteriormente el redactor técnico trataba al manual como un todo, la tendencia ahora es, claramente, organizar el contenido en torno a bloques discretos de información a los que llamamos artículos. La popularización de modelos de información como el propuesto por la especificación DITA han cimentado esta transformación.

A pesar de este avance, modelos como DITA siguen sin dar respuesta a cómo los artículos, entendiendo estos como bloques primarios de información, se relacionan entre sí de forma lógica para el lector. De hecho, en la teoría de la escritura orientada al artículo, la agrupación de artículos se desaconseja o se considera que va en detrimento de la capacidad de asimilar información por parte de lector (en una palabra, de su usabilidad). Tal como expone el comunicador técnico Tony Self en su artículo Desarrollo de información basada en artículo (originalmente en inglés, Topic-based Information Development):
Los cambios en los patrones de lectura y adquisición de información sugieren que los lectores ya no quieren leer en profundidad textos largos y lineales. En su lugar, la investigación sugiere que quieren leer de forma superficial, y leer sólo el mínimo que les permita realizar una tarea. Las estructuras de información basadas en artículos son más apropiadas para estos lectores impacientes.
Pero si, como definen estos modelos, cada artículo representa únicamente un tipo de información (tarea, referencia, concepto, etc.), ¿no corremos el riesgo de volver a aquellos manuales electrónicos del pasado, con múltiples entradas aisladas y difíciles de manejar? ¿No tendría más sentido agrupar funcionalmente aquellos artículos relacionados entre sí, incluso aunque pertenezcan a categorías distintas?

El hecho de que los patrones de lectura y adquisición de información hayan cambiado con la aparición de internet no está reñido con la creación de contenido de mayor longitud. Muy al contrario. De hecho, la extensión de un artículo, por sí sola, no debería ser un criterio válido para fragmentar el contenido. Muchas entradas de la Wikipedia incluyen artículos extensos, lo que como lectores no nos impide navegar por su contenido en busca de la información o dato necesarios. Sin duda, esta organización resulta mucho más útil que presentar la información en bloques discretos y discontinuos, obligando al lector a moverse de un nivel de contenido a otro, y rompiendo el patrón de lectura habitual.

Modelo A frente a modelo B

Los modelos de desarrollo de información basados en DITA, en un empeño por maximizar la capacidad de reutilizar el contenido (uno de los principales objetivos de la escritura orientada a artículos) son incapaces de dar respuesta al modo en que estos bloques se agrupan (tanto es así, que algunos autores no consideran DITA como un verdadero modelo de información).

El modelo A (ver imágen) ejemplifica el modelo propuesto por DITA. Bajo esta concepción, cada tipo de artículo se presenta como un elemento final y reutilizable de información. El modelo B, por el contrario, plantea que los distintos artículos se combinan en elementos de mayor entidad, a los que me he dado en llamar meta-artículos. Si el artículo supone el elemento constructor de la información, el meta-artículo constituye el elemento funcional.

El modelo A aconseja aislar las tareas de autoría de las de presentación. En palabras de Tony Self:
El formato y presentación son consideración posteriores a la autoría, y actividades posiblemente no realizadas por el autor técnico.
Pero, ¿es esto cierto? En mi opinión, este planteamiento ignora que la presentación del contenido (el cómo se relacionan entre sí los diferentes tipos de artículos) condiciona en gran medida el acceso a la información por parte del lector. El redactor puede y debe aislarse de elementos formales como el uso de fuentes, colores, espacios entre párrafos, etc., pero no puede ignorar la estructura final del artículo.

El decidir entre un modelo u otro dependerá de factores que, como redactores técnicos, deberemos sopesar para cada tipo de contenido y audiencia. Veamos dos casos para ilustrar esta idea. Pensemos por un momento en una aplicación ofimática como Microsoft Word. Las preguntas que un usuario de esta aplicación puede plantearse se resuelven normalmente con una breve explicación (añadir formato a una tabla, compartir un documento, insertar una ecuación, etc.). En estos casos, la información de contexto resulta innecesaria porque el objetivo del usuario es muy específico y el número de posibilidades muy reducido. Pero pensemos ahora en una caso más complejo, como puede ser la instalación y configuración de un servidor web. El técnico que se enfrenta a esta tarea requiere una información de contexto suficiente para entender aquello que va a llevar a cabo y evitar errores comunes. ¿Tiene sentido aquí separar la tarea en sí de la información de contexto? Separando ambas (por ejemplo, en dos artículos enlazados) perdemos la posibilidad no solo de atraer la atención del lector, sino también de facilitarle la información necesaria en el lugar donde se lleva a cabo su acción.

Usabilidad frente a reutilización

El problema se reduce, por tanto, a cómo presentar el contenido al usuario de una forma que sea coherente con su flujo de trabajo, y que a su vez permita reutilizar la información. DITA no cierra la posibilidad de agrupar diferente artículos, pero advierte contra los peligros de hacerlo, como podemos leer en la propia especificación de DITA 1.2:
Los artículos pueden definirse dentro de otros artículos. Sin embargo, la unión requiere un cuidado especial porque puede dar lugar a documentos complejos que son menos utilizables [en el sentido de usabilidad] y reutilizables.
Como enfatiza Mark Baker, el problema es que DITA prioriza la posibilidad de reutilizar un contenido sobre la usabilidad del mismo. El argumento de que la agrupación de los artículos hace el documento menos usable no parece sostenerse. De hecho, si nos fijamos, la usabilidad de un documento (en otras palabras, la capacidad de ese documento de aportar la información relevante para la tarea del usuario) es contraria en muchos casos a las posibilidades de reusar el contenido. Pensemos en las imágenes o los vídeos. Aunque la tendencia es ahora la de incorporar cada vez más elementos gráficos en la documentación técnica, durante mucho tiempo este contenido fue relegado por los costes de producción asociados y su escasa reutilización. Pero, ¿es este un contenido usable? ¿Da soporte a la tarea en cuestión que el usuario realiza? Claramente, la respuesta es sí. Usabilidad y capacidad de reutilización son, en muchos casos, elementos contrapuestos.

El meta-artículo da respuesta a la necesidad de desarrollar documentación que sea a la vez usable y reutilizable, y comienza a estandarizarse como la forma más adecuada de hacer llegar la información técnica al usuario, especialmente en tareas complejas como las que se llevan a cabo en los departamentos de IT.

Organizar la información en el artículo técnico

La estructura del artículo técnico tiene un papel clave en la búsqueda y descubrimiento de información por parte del lector. Los artículos deben mostrar elementos comunes que den soporte a esta búsqueda, pero también elementos diferenciadores que permitan identificar si la información es relevante en el contexto de la tarea.

Estructura y búsqueda de información

Cuando analizamos a los usuarios -o a nosotros mismos- utilizando documentación técnica, observamos que el patrón de lectura dista mucho de el que el lector adopta con una novela. Inicialmente, con un vistazo general a la estructura, juzgamos ya si la información que contiene el documento responde o no a nuestras necesidades. Una vez hemos decidido que la información que tenemos delante puede sernos útil, hacemos un análisis -aún muy superficial- de elementos como títulos, listados, imágenes o tablas. Solo entonces centramos nuestra atención en párrafos o elementos particulares que consideramos relevantes. Este análisis está en sintonía con lo que Nielsen describió como information foraging (literalmente, tratar la búsqueda información como la búsqueda de alimento o forraje por parte de un animal).

Este mecanismo de búsqueda y descubrimiento, aparentemente errático, sigue un patrón determinado muy similar al que empleamos al leer cualquier otro tipo de información en internet. De esta observación podemos concluir que no basta con que la información sea completa y correcta, es necesario además que su estructura permita identificar dónde está el contenido de interés -informacion suculenta, siguiendo con la idea de Nielsen- mediante una organización predecible y sencilla. Recordemos que la documentación no busca entretener al lector, sino facilitarle el acceso a la información en sus propios términos.

Especialmente en el caso del redactor técnico accidental -aquel cuya principal tarea no es la redacción técnica-, la experiencia y las herramientas que permiten organizar adecuadamente la información no siempre están disponibles. Este artículo, el primero de una serie de tres, propone una forma estandarizada y sencilla de estructurar un texto técnico, independientemente del método y herramienta de desarrollo.

Tipología del artículo técnico

La clasificación que aquí se presenta está basada en DITA, una especificación XML muy popular en el desarrollo de documentación. Pero esta clasificación no pretende llegar al nivel de complejidad y detalle que alcanza DITA sino, bien al contrario, servir de referencia rápida y accesible para el redactor.

Al analizar diferentes artículos técnicos, observamos que la inmensa mayoría responden a uno de los siguientes tipos:

  • Concepto
  • Tarea
  • Referencia
  • Resolución de problemas

Estos 4 tipos constituyen la base sobre la que se articula la información. No entraremos aquí en cómo estos elementos se combinan entre sí para construir artículos de mayor entidad. Esta explicación se deja para el último artículo de la serie, donde se desarrolla en más detalle el concepto de artículo. Es suficiente con decir ahora que la mayoría de los escritos técnicos resultan de combinar estos tipos. Veamos un ejemplo. Supongamos que nuestro encargo consiste en redactar un artículo sobre cómo configurar una solución de alta disponibilidad para un sistema en el que nuestro departamento de IT está trabajando. El texto final podría tener el siguiente esquema:

  1. Introducción a la solución de alta disponibilidad (concepto).
  2. Explicación sobre el modo de instalación y configuración (tarea).
  3. Lista de comandos especiales para operar la solución (referencia).
  4. Problemas más comunes (resolución de problemas).
Vemos en este ejemplo que el trabajo final está conformado por los 4 tipos de artículos descritos, siguiendo un orden lógico de acciones.

Elementos básicos del artículo

Cada tipo de artículo está compuesto por un conjunto ordenado de elementos. Varios elementos son comunes a los 4 tipos, otros son particulares. El siguiente esquema muestra los elementos comunes:

Los elementos con un asterisco (*) son necesarios en la estructura del artículo, mientras que aquellos con un signo de cierre de interrogación (?) son opcionales. El siguiente listado es una descripción de los elementos comunes:

  • title: título del artículo.
  • shortdesc: breve introducción a la información que se va a tratar en el artículo. Puede ser una frase o un párrafo.
  • keywords: términos o palabras clave en el artículo que son normalmente empleados por los motores de búsqueda.
  • toc: tabla de contenidos. Aunque opcional, es recomendable en artículos extensos compuestos por varias partes.
  • body: representa el cuerpo del artículo, donde se encuentra la información que lo compone (texto, imágenes, tablas, listas, etc.). El elemento body marca la diferencia entre los distintos tipos de artículo.
  • related-links: enlaces a otros artículos relacionados.
Veamos ahora con más detalle los 4 tipos de artículo mencionados.

Concepto

El concepto proporciona la respuesta a la pregunta Qué es. Este tipo de artículos presenta la información necesaria para entender otros conceptos o realizar una tarea. Es común incluir este tipo antes de explicar tareas complejas o que requieren información de contexto para poder ser completadas. Un artículo de este tipo muestra la siguiente estructura:


En este caso el contenido se desarrolla dentro del elemento descbody. El concepto es además el único tipo de artículo que puede incluir todos los demás tipos. Un ejemplo esquemático de este artículo sería el siguiente:

Tarea

La tarea da respuesta a la pregunta Cómo. Este tipo de artículo muestra paso a paso cómo completar una acción determinada. Los artículos que describen tareas incluyen los siguientes elementos:

Como podemos ver en la imagen, las tareas pueden a su vez incluir otras tareas. El contenido particular de este artículo se encuentra en el elemento taskbody. Cada tarea se compone de una serie de pasos ordenados (steps) que pueden venir o no precedidos de uno o más requerimientos (req). Los requerimientos hacen referencia a otras acciones que han de completarse con anterioridad o a materiales necesarios durante el proceso.

El artículo debe contener la información necesaria sin extenderse en explicaciones. Un error común es el de incluir información en la descripción de la tarea. En la medida de lo posible, esta información debe desarrollarse en el artículo de tipo concepto. Este artículo muestra la siguiente estructura:

Referencia

Una referencia incluye un listado de opciones y parámetros que son útiles para completar una tarea o para usar una función específica de un software. Ejemplos de referencia son los artículos donde se muestran las opciones de un comando, los parámetros de configuración de un determinada aplicación o la descripción de una API (interfaz de programación de aplicaciones). En muchos casos se utilizan tablas o listados para presentar la información. Estos elementos se incluyen en el apartado refbody. Los artículos de referencia se componen de los siguientes elementos:

Al igual que ocurre con las tareas, un mismo artículo puede contener varias referencias, aunque los artículos de referencia demasiado extensos son difíciles de usar incluso con una tabla de contenidos. El artículo de tipo referencia atiende la siguiente estructura general:

Resolución de problemas

El artículo de resolución de problemas detalla información de un problema o error en el software. La información debe permitir al lector identificar el problema con el que se encuentra (symptoms), entender las causas que lo originan (more-info) y mostrar los pasos requeridos para eliminar o mitigar el problema (tasks). Este tipo de artículo se caracteriza por incluir los siguiente elementos:

y muestra la siguiente estructura general:


Tanto la clasificación como los elementos discutidos aquí son comunes a una gran cantidad de documentos técnicos. No se busca en ningún caso ofrecer un planteamiento original, precisamente porque las estructuras familiares y comúnmente aceptadas son clave en el descubrimiento y consumo de la información.

Trabajar con referencias externas en documentación técnica

Nuestra labor como redactores técnicos es proporcionar información fiable, adaptada y relevante, pero también facilitar el acceso a otra información cuando la nuestra resulta insuficiente. Utilizar referencias a otras fuentes de forma adecuada requiere un estudio que es anterior al desarrollo del contenido.

Las referencias externas se definen como enlaces en nuestro contenido a otro contenido fuera de nuestro control. Se incluye también aquí la información tomada de otro documento e incluida en el nuestro, aunque no vaya acompañada de un enlace o URL. Las referencias internas, por el contrario, son aquellas que enlazan con contenido sobre el que sí mantenemos un control. En documentación técnica, estas referencias son normalmente enlaces a páginas web o artículos y, en menor medida, referencias bibliográficas como las que suelen encontrarse en artículos científicos.

Si trabajamos con un manual pequeño, incluir y actualizar referencias no debería suponer un gran problema. En manuales extensos, por el contrario, la gestión puede llegar a ser compleja y muy costosa en tiempo. Esta circunstancia hace necesario planificar cada artículo por adelantado, estableciendo qué contenido externo es necesario y la mejor manera de incorporarlo a nuestro texto. A continuación se discuten algunas recomendaciones para trabajar con la información de otros manuales en nuestra documentación.

Información y acción

El contenido de un texto técnico se puede sintetizar en la suma de información y acción. La información proporciona el contexto para entender una tarea, mientras que la acción describe la tarea en sí. Información y acción son elementos complementarios -aunque como usuarios frecuentemente empleamos solo de uno de ellos- y las características de uno y otro son relevantes en el tratamiento de referencias.

Tengamos en cuenta que al buscar información sobre una materia en particular, normalmente lo hacemos moviéndonos -saltando- de un contenido a otro sin dar demasiada importancia a este proceso. Pensemos por un momento en cómo usamos Wikipedia, donde saltamos de un artículo a otro buscando y complementando la información de interés. Por el contrario, cuando realizamos una tarea, esperamos que la información que se nos presenta sea suficiente para completarla sin necesidad de recurrir a otra fuente. En la búsqueda de información nuestra atención sigue un patrón (aparentemente) aleatorio, mientras que en la realización de tareas sigue un patrón lineal.

Teniendo esto en cuenta, si la referencia que vamos a añadir es informativa, conviene enlazar a ella en lugar de añadirla directamente en nuestro documento. Por el contrario, si la referencia que vamos a añadir forma parte de una acción, es más efectivo incluirla directamente en nuestro documento.

Usar elementos o etiquetas identificativas

A medida que el número de reseñas en nuestro texto aumenta, resulta más necesario llevar un registro de las mismas. Las herramientas de edición normalmente nos permiten emplear algún elemento identificativo con el que, posteriormente poder obtener un listado de todas estas referencias.

En editores avanzados tales como FrameMaker, podemos usar elementos y atributos XML para identificar y posteriormente filtrar el contenido que buscamos. En otros editores, como Microsoft Word, podemos hacer uso elementos como el texto oculto para guardar un registro de esta información que no será visible al imprimir o generar un archivo PDF. Tengamos en cuenta que no todas las referencias aparecen en forma de enlace; algunas son simplemente fragmentos de texto, listados o tablas de otros manuales. Usar una URL no siempre es la mejor opción.

Trabajar con herramientas especializadas solo cuando es imprescindible

Pero, ¿por qué no usar programas especializados para llevar un registro de las referencias? Es preciso aquí hacer una llamada de atención sobre este software: su uso no es sencillo.

Emplear o no herramientas específicas dependerá en gran medida del número de referencias que manejamos. En documentos pequeños, con un número reducido de enlaces externos, no usar ningún tipo de software puede ser la mejor opción. Citando a Mamishev:

Si el número de referencias con las que trabajas es pequeño, olvida los programas especializados y procésalas manualmente [...]. Si, por otro lado, necesitas escribir un artículo para una publicación especializada o una tesis, el tiempo invertido en aprender la técnicas de gestión de referencias se te devolverá con creces [...].

Evitar URLs a contenido externo

El problema de utilizar URLs para enlazar con contenido externo es que estas cambian con relativa facilidad. Esta circunstancia puede provocar enlaces rotos en nuestros artículos, algo que los usuarios no suelen apreciar. Resulta más óptimo indicar al lector el asunto al qué referirse, junto con una llamada genérica a la documentación en cuestión. Por ejemplo:

en lugar de:
Para más información sobre la configuración de memoria en SQL Server, revisar la siguiente información en https://msdn.microsoft.com/en-us/library/ms178067.aspx

podemos usar:
Para obtener más información sobre la configuración de memoria en SQL Server, consultar la documentación de Microsoft MSDN.

Algunos verán aquí un paso atrás en nuestra labor de facilitar la tarea al usuario. Pero eso supondría subestimar la capacidad de los motores de búsqueda para mantener la información actualizada -sin duda, mucho mejor que la nuestra- y la del usuario para encontrarla.

Incluir la información para advertir de posibles errores

Si la acción que vamos a describir afecta a un software de otro fabricante y puede ser causa de problemas, conviene añadir esta información literalmente en nuestro documento. Por ejemplo, Microsoft advierte del riesgo de modificar el Registro de Windows (un componente esencial del sistema operativo) en muchos de sus artículos técnicos. Si durante el desarrollo de una tarea requerimos del usuario una acción similar, debemos también advertir explícitamente del riesgo que conlleva.

Usar un sección Referencias al final del artículo

Una tendencia bastante común -especialmente en el caso de documentación en formato electrónico- es la de añadir al artículo una sección con otros enlaces de interés. Esta sección, que normalmente encontramos al final del texto bajo el nombre de Más información, es fácilmente reconocible por el usuario, y proporciona una vía de salida cuando nuestro contenido ya no resulta relevante o es insuficiente.

Respetar el copyright y nombrar las fuentes referenciadas

Algunos fabricantes permiten copiar libremente su información, mientras que otros limitan esta posibilidad la documentación destinada a un uso interno. Siempre es recomendable revisar la normas de copyright que el fabricante tiene para su documentación y, por supuesto, respetar estas normas.