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

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.

Escribe historias, no interfaces

Resulta curioso observar cómo, mientras las aplicaciones para la web y dispositivos móviles tienden a simplificar la interfaz de usuario con el paso del tiempo, las aplicaciones para escritorio parecen seguir un camino opuesto. La solución adoptada para añadir nuevas funcionalidades a un programa sigue siendo, en muchos casos, incorporar más elementos a la interfaz, generalmente sin la adecuada planificación y en detrimento de la usabilidad. La documentación del producto puede suplir esta deficiencia si los escritores técnicos entendemos que nuestra función es la de describir tareas -contar historias- y no interfaces.

Hace unos días necesitaba revisar la información de un documento de trabajo bastante extenso. Al no disponer de mucho tiempo, pensé que la mejor opción sería imprimir el documento en formato libro para poder leerlo en el camino de regreso a casa sin desperdiciar mucho papel -con documentos largos, resulta incómodo hacer esto en la pantalla del móvil. En el momento de imprimir el documento me encontré con el siguiente cuadro de impresión que, con pocas variaciones, será familiar para muchos de los que trabajamos en una oficina:


Me considero un usuario de ordenadores avanzado, pero reconozco que me costó un par de impresiones fallidas encontrar la combinación de opciones para conseguir el formato deseado -dando al traste con mis buenas intenciones de ahorrar papel y ayudar al medio ambiente. El caso particular del software de impresión es paradigmático porque, después de décadas de desarrollo, su uso sigue siendo complejo y, en muchos casos, encontrar la opción adecuada continúa siendo una cuestión de prueba y error.

En el año 2000, Steve Krug publicó su famoso Don’t Make Me Think (del inglés, No Me Hagas Pensar) introduciendo un concepto por entonces desconocidos para la inmensa mayoría: la usabilidad. El libro fue un éxito casi inmediato y, con el paso del tiempo, se ha convertido en un clásico. Es mucho lo que se ha avanzado en este sentido desde entonces, especialmente en el diseño de páginas web y, más recientemente, de aplicaciones para dispositivos móviles. Pero a pesar de todos estos avances, el uso de las aplicaciones que instalamos en nuestros equipos sigue siendo poco intuitivo. Pensemos por un momento en los paquetes de ofimática o de diseño gráfico que encontramos y usamos habitualmente, y que incorporan un conjunto de opciones tan grande como intimidante. Esta complejidad dista mucho de la facilidad de uso a la que las aplicaciones para móviles nos han acostumbrado. Parecería que, mientras que las aplicaciones diseñadas para dispositivos móviles o para la web han llevado a cabo una necesaria simplificación, aquellas instaladas en nuestros ordenadores han seguido el camino opuesto.

Es justo reconocer que mantener la sencillez y facilidad de uso de un programa resulta complejo. La evolución del software, por su propia función, es entrópica. Incluso programas que comienzan con un número limitado de opciones de configuración, suelen acabar en un conglomerado de menús y botones al cabo de pocas versiones. Mantener la usabilidad y simplicidad resulta difícil porque la tendencia natural del software es la de incorporar un número creciente de opciones. La solución en estos casos pasa hoy por arrojar -normalmente sin demasiado acierto- más elementos a la interfaz, lo que se traduce en un uso cada vez más complejo para el usuario.

Hay dos razones fundamentales que explican este hecho. Por un lado, el fabricante del software entiende que la evolución de su producto tiene que venir por la incorporación de nuevas funcionalidades y opciones. La demanda de los usuarios y la competencia de otros productos dejan pocas alternativas. Incorporar estos cambios manteniendo la usabilidad requiere un gran esfuerzo por estudiar, en una fase temprana, cómo interaccionan los usuarios con el software, y encontrar soluciones imaginativas a los problemas detectados. Un ejemplo clásico de este tipo de soluciones lo tenemos en la aparición del Ribbon (o Cinta) en Microsoft Office, un elemento de la interfaz que redujo la complejidad de un número creciente de opciones y menús, permitiendo que el usuario pudiera trabajar con estos programas sin sentirse abrumado. Otro ejemplo más reciente lo tenemos en Google que, tomando como base su iniciativa de simplificación de interfaces denominada Material Design (del inglés, Diseño Material), ha adoptado una solución visualmente atractiva -y efectiva- para mostrar al usuario sus opciones de configuración de cuenta.


Por otro lado, mantener la usabilidad de una interfaz requiere una decisión valiente y arriesgada por parte del fabricante. Valiente porque limitar el número de opciones visibles -en lugar de incorporar otras nuevas- supone adoptar decisiones en nombre del usuario. Y arriesgada porque la simplificación puede dejar fuera a aquellos usuarios que esperan cada vez más funcionalidades del producto. Un ejemplo de esto lo encontramos en Apple que, de forma premeditada, oculta opciones avanzadas de configuración en su sistema operativo de escritorio OS X, con el objetivo de simplificar el trabajo de los usuarios menos avanzados. Aunque menos visible en las últimas versiones de su sistema operativo, la facilidad de uso ha sido siempre una característica de la marca (característica que el escritor Ken Segall, autor del libro Increíblemente Simple, considera la clave del éxito de Apple).

Pero, ¿en qué modo afecta todo esto a la documentación de un producto? Cuando una interfaz es compleja, nuestra obligación como escritores técnicos es ofrecer una interfaz mejor, que cuente al usuario aquella historia que el software no puede contar. La documentación ha de ser la nueva interfaz entre el usuario y aquel programa que se resiste a la simplificación. Las guías de usuario no pueden seguir siendo una descripción aséptica de opciones, menús y botones sin relación aparente, han de ser el relato que encaje con la tarea que el usuario se dispone a realizar. Debemos abandonar la idea de describir interfaces y comenzar a escribir tareas o, si preferimos llamarlo así, historias.

Hacer una descripción de todos los elementos y controles en pantalla puede ser de gran utilidad para el usuario avanzado, pero obliga al menos experimentado -precisamente el más común- a intentar descifrar qué opciones llevan a conseguir el resultado esperado. En el manual de la impresora de mi oficina, al que se podía acceder directamente desde el botón Help (Ayuda) de la ventana de impresión, se avanza un poco en este objetivo de describir tareas, añadiendo algunas acciones comunes de impresión en Métodos de impresión de uso frecuente -mi opción de impresión en formato libro parece no ser frecuente. Sin embargo, la escasa información de este apartado contrasta con la explicación detallada de cada uno de los controles de la interfaz en el apartado Ajustes que se pueden cambiar en cada menú.

El software debe aspirar a ser fácil e intuitivo. Pero trasladar la simplicidad de una aplicación móvil a una de escritorio es, en la práctica, complejo. Los fabricantes pueden y deben invertir más en usabilidad ya desde la fase de concepción del producto -y no como un elemento más a añadir tras el desarrollo. Donde esto no suceda así, la documentación debe ser capaz de rellenar ese hueco.

Consejos para mejorar tu documentación técnica

La documentación es una herramienta fundamental en el día a día los departamentos de IT. Elaborar guías adaptadas a las necesidades concretas de cada equipo es clave a la hora de compartir información y experiencia. Una características común a estos documentos de uso interno son las diferencias en el estilo y el formato con el que se presenta la información. Este artículo muestra consejos sencillos para mejorar esta documentación.

Una buena parte de las guías de referencia que se generan en los departamentos de IT encuentran en formato Word o PDF. Word sigue siendo el programa de edición más común dentro y fuera del mundo de la empresa. Pero resulta llamativo que, a pesar de las opciones incorporadas a este software a lo largo de los años, la forma en la que lo usamos hoy no es muy distinta de la de hace 20 años. Parece razonable preguntarse, ¿es esta la mejor opción?

Antes de aventurarnos en la redacción del documento, pensemos por un momento en la mejor forma de hacer llegar el contenido a nuestra audiencia. Si tenemos en cuenta que las guías técnicas elaboradas por equipos de IT son normalmente de uso interno, parece tener sentido trabajar en algún medio web al que los usuarios puedan acceder fácilmente y en el que sea posible realizar comentarios de forma sencilla, como una wiki o el propio Google Docs. Estos medios permiten incorporar el ciclo de revisión dentro del propio ciclo de vida del documento, es decir, no hay un tiempo delimitado para revisar el documento o publicar una nueva versión ya que el contenido está siempre actualizado y siempre disponible para su revisión.

He extraído este listado de recomendaciones basándome en un documento interno que se me pidió revisar. Casi todos los ejemplos utilizados están tomados de la documentación técnica de Microsoft en MSDN.

Escribe con un lenguaje sencillo y directo

Al escribir un documento técnico debemos acercarnos al punto de vista del lector, utilizando siempre un tono directo y empático. El uso de palabras y expresiones sencillas debe ir acompañado del uso del término adecuados en todo el texto. Cuando empleamos términos distintos para referirnos a una misma cosa, el lector no familiarizado con la materia puede asumir que en realidad estamos hablando de cosas distintas. Evitemos también usar jerga o acrónimos que no son de uso común.

Usa la voz activa siempre que sea posible

Adoptar la voz activa nos acerca al usuario del documento y simplifica la comprensión del texto. En este caso es el usuario -o el objeto de la acción- y no la acción, quien adopta el papel activo. Veamos dos ejemplos de uso de la voz pasiva y su correspondiente cambio a voz activa:

Voz pasiva:

The backup process can be canceled at any time. / El proceso de copia de seguridad puede ser cancelado en cualquier momento.

The encryption mechanism is provided by the background secproc.d daemon. / El mecanismo de encriptación es realizado en segundo plano por el demonio secproc.d.

Voz activa:

You can cancel the backup process at any time. / Puedes cancelar el proceso de copia de seguridad en cualquier momento.

The secproc.d background daemon provides the encryption mechanism. / El demonio  secproc.d realiza en segundo plano el mecanismo de encriptación.

Utiliza la forma presente del verbo

Usar de la forma presente del verbo facilita la comprensión del texto y proporciona al lector seguridad sobre sus acciones. Veamos un ejemplo usando la forma futura:

To continue, click Install. SQL Server Setup will first install the required prerequisites. / Para continuar, haz clic en Instalar. El Instalador de SQL Server instalará primero los prerrequisitos necesarios.

y el mismo ejemplo con la forma presente:

To continue, click Install. SQL Server Setup installs the required prerequisites first. / Para continuar, haz clic en Instalar. El Instalador de SQL Server instala primero los prerrequisitos necesarios.

Elimina las palabras innecesarias

Como ya he comentado, una de nuestras prioridades es acercar el documento al lector, mediante un lenguaje sencillo y evitando construcciones complejas. Por ejemplo, la siguiente expresión:

In order to complete the backup process select Finish. / Con el fin de completar el proceso de copia de seguridad, selecciona Finalizar.

la podemos simplificar fácilmente:

To complete the backup process, select Finish. / Para completar el proceso de copia de seguridad, selecciona Finalizar.

Otro ejemplo es el uso de palabras innecesarias como recommended (recomendado) o please (por favor):

It is recommended to use a high-performance drive for the database journal. / Es recomendable usar un disco de alto rendimiento para el journal de la base de datos.

Como autores del documento, se da por sentado que lo allí escrito es nuestra recomendación. Podemos simplificar esta expresión diciendo:

Use a high-performance drive for the database journal. / Utiliza un disco de alto rendimiento para el journal de la base de datos.

En el caso de please, se emplea generalmente para rebajar -digámoslo así- el carácter imperativo del uso de la voz activa. Siempre que el tono y voz general del documento sea sencillo y directo, no debemos preocuparnos por esta cuestión.

Usa las imágenes de forma correcta

Una de las razones por las que el uso de las imágenes es escaso en la documentación técnica profesional es que su gestión es compleja. Si además estas imágenes tienen que mostrarse en diferentes idiomas, el problema se multiplica. Antes de incluir una nueva imagen, debemos plantearnos si hacerlo aporta valor a aquello que queremos describir. Estas son algunas pautas al tratar imágenes:

Incorpora imágenes para aclarar el funcionamiento de interfaces

Esta situación se da en interfaces de usuario pobremente diseñadas, donde el flujo de acciones que ha de seguir el usuario para completar la tarea no está claro. En estos casos conviene añadir imágenes resaltando los elementos de la interfaz necesarios para completar la tarea. Una imagen bien empleada puede simplificar enormemente el flujo de trabajo del lector.

Añade un borde estándar para las capturas de pantalla

Cuando tengamos que pegar capturas de pantalla en un texto, es conveniente añadir un borde a la imagen. De esta forma evitamos el fondo de la imagen se confunda con el fondo del documento, provocando una separación desigual de los elementos en pantalla:

Ajusta el tamaño de la imagen a la acción que estamos describiendo

Debemos evitar usar capturas de pantalla que incluyen un area demasiado grande o demasiado pequeña. Si el paso que estamos redactando describe un cuadro de diálogo concreto en la interfaz de usuario, carece de sentido incluir una captura de pantalla de todo el escritorio.

Divide tareas complejas en subtareas

Las tareas con un gran número de pasos son más difíciles de seguir y entender. Pensemos que si el lector ha de fijar su atención en una tarea que tiene 32 pasos, es fácil que pierda la atención en algún momento, con el riesgo añadido de dejar atrás algún paso esencial dentro del proceso. No siempre es posible describir una tarea con un número reducido de pasos, pero siempre podemos dividirla en subtareas.

Usa listas y flujos para resumir procesos complejos

La instalación y configuración de ciertos paquetes de software puede llegar a ser enormemente compleja. Normalmente esto sucede cuando el flujo de acciones no es único, o cuando se llevan a cabo varias acciones en paralelo. En todos estos casos es casi imprescindible acompañar el texto con un diagrama de flujo (workflow) que permita entender la tarea en su conjunto. Estos diagramas no son fáciles de realizar, pero el tiempo invertido en ellos aporta un gran valor al documento.

En otros casos, el lector está muy familiarizado con en el proceso que se va a realizar, pero necesita una guía de referencia rápida. Es lo que comúnmente llamamos una lista de comprobación o checklist. Al trabajar con estas listas, lo más común es añadirlas o enlazarlas al final del documento como un anexo.

Describe una acción completa en cada paso

Cada paso en un proceso define una acción completa del usuario. Veamos un ejemplo:

4. In the right pane of the Database Engine Tuning Advisor GUI, type MySession in Session name.

5. Select File for your Workload, and click the Browse for a workload file button to locate the MyScript.sql file that you saved in Step 1.

El paso 5 en esta tarea incluye varias acciones (select, click, locate) pero todas ellas forman parte de una misma acción completa (cargar un fichero en el programa).

Si es necesario realizar alguna aclaración sobre una acción, es mejor hacerlo dentro del paso correspondiente de la tarea, y no como un nuevo paso. El siguiente ejemplo ilustra la forma correcta de añadir esta información:

10. On the Feature Selection page, select the components for your installation.

SQL Server Setup will install the prerequisite that are not already installed during the installation step described later in this procedure.

11. On the Server Configuration — Service Accounts page, specify login accounts for SQL Server services.

En el siguiente ejemplo el uso no sería correcto, ya que el paso 2 no es realmente un paso en la tarea, sino una aclaración sobre el paso anterior:

1. Click the import configuration button.
2. The Configuration import dialog appears.

3. Wait until the end of the process.

Establece un formato único para elementos comunes

Usar un estilo unificado para los elementos de la interfaz mejora el aspecto visual del documento y facilita su lectura. Habitualmente queremos destacar tres elementos al describir un proceso:

  • Nombres de ficheros o carpetas.
  • Elementos de la interfaz de usuario (botones, menús, etc.).
  • Ejecución de sentencias o comandos.

Debemos definir un único estilo para esto tres elementos y ser constantes en su uso a lo largo del documento. Este sería un ejemplo que podemos tomar como punto de partida:

Elemento: Nombres de ficheros o carpetas
Estilo: Letra cursiva. Ejemplo: Double click the setup.exe file.

Elemento: Componentes de la interfaz de usuario.
Estilo: Letra negrita. Ejemplo: Click Run and then click OK.

Elemento: Código, sentencias o comandos.
Estilo: Letra de ancho fijo. Ejemplo: Type <setup.exe /a> to start the setup process

A pesar de la extensión y profundidad común a todas las guías de estilo, la mejora más inmediata y apreciable se consigue con la aplicación de un conjunto de normas sencillas. Recordar y practicar estas normas no es complejo, y el beneficio a corto y largo plazo será considerable.