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.