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.


Documentar la interfaz de comandos (II)

Este artículo es la segunda parte del conjunto de recomendaciones para describir la interfaz en línea de comandos. La primera parte introdujo conceptos de terminología y estilo. En esta segunda, descubriremos cómo documentar tareas que se suceden en esta interfaz.

Describiendo la ejecución de comandos

Al describir las acciones del usuario en este tipo de interfaces, debemos distinguir claramente entre el texto que acompaña a la instrucción y explica el objetivo y el texto destacado que indica cómo realizar la tarea en la interfaz. El siguiente esquema muestra esta organización:


Veamos el siguiente ejemplo:


En el ejemplo se muestra cómo instalar un paquete de software (nmap, en este caso) en Ubuntu Linux, utilizando la herramienta apt-get. El texto introductorio “Install a package: Installation of …” indica cuál es la finalidad o resultado de la acción, pero no hace una descripción de la instrucción sudo que aparece inmediatamente después. Veamos otro ejemplo:


De nuevo aquí, vemos como el texto que acompaña a la descripción del comando ("To add an Ethernet connection…") no describe el comando a ejecutar, sino el objetivo de ejecutar este comando. Si describimos el comando de la siguiente forma, la información sería redundante:


Describiendo tareas

En algunos casos, la interfaz en línea de comandos es el medio para completar una tarea, como instalar un paquete de software o realizar una copia de seguridad de una base de datos, por poner solo dos ejemplos. En estos casos, normalmente el usuario no se limita a ejecutar comandos sino que interactúa con la interfaz respondiendo preguntas o aportando los datos necesarios para completar la tarea. Veamos el siguiente escenario, donde se describen dos pasos en el proceso de copia de seguridad de una base de datos:


Podemos ver que las cajas de texto no muestran en realidad la ejecución de ningún comando, sino el desarrollo de la tarea en la interfaz. Este mismo ejemplo podría resumirse de la siguiente forma, con -aparentemente- poca o ninguna pérdida de información para el usuario:


Sin embargo, mostrar cómo se van sucediendo las acciones en la interfaz ayuda a situar al usuario en el proceso. Las cuadros de texto que acompañan a cada paso destacan la acción que ocurre en la interfaz en ese momento y actúan como anclajes visuales para el lector, algo que es especialmente importante en procesos largos o complejos. En estos casos, destacamos mediante letra negrita o cursiva aquellas acciones en pantalla que o bien el usuario tiene que teclear para realizar el proceso o que aportan información clave sobre la acción.

En otros casos, como en el siguiente ejemplo, no hay ningún tipo de interacción por parte del usuario, pero se muestran estas acciones para señalar qué tipo de resultado se puede esperar:


Como siempre, el objetivo no es saturar al usuario con información, sino aportar elementos que le permitan reconocer con mayor rapidez en qué parte de la tarea se encuentra y qué resultado puede esperar de las acciones que se suceden.

La Guía de Estilo de IBM contiene una descripción minuciosa de las normas de estilo al documentar la interfaz de comandos. Sin llegar al nivel de detalle de esta guía, este artículo pretende ser una referencia rápida que, con una inversión mínima de tiempo, permita dotar de un estilo común y coherente nuestra documentación.

Documentar la interfaz de comandos (I)

La interfaz en línea de comandos, por sus características, requiere un tratamiento particular en documentación. El siguiente artículo presenta un resumen de normas que podemos encontrar en diferentes guías de estilo sobre escritura técnica, o cuyo uso se ha estandarizado con el paso del tiempo. El artículo está dividido en dos partes. Esta primera introduce conceptos de terminología y estilo mientras que en la segunda descubriremos cómo documentar tareas en esta interfaz.

Elementos de la interfaz en línea de comandos

Antes de comenzar a documentar, es imprescindible definir los elementos que forman parte de la interfaz. Es importante señalar que los términos que aquí se indican no se corresponde necesariamente con una traducción del inglés, sino con la forma de uso más generalizada. La mayoría de referencias se acompañan también del término más común en inglés.

Diferenciamos, por un lado, componentes de la interfaz en sí, y por el otro, las instrucciones que se escriben en ella. Los componentes de la interfaz son:

  • La interfaz en línea de comandos (en inglés, command-line interface) es una interfaz de un sistema, dispositivo o instrumento a través de la cual podemos ejecutar acciones mediante comandos escritos.
  • La aplicación donde se ejecutan los comandos se denomina símbolo del sistema (command prompt) en Windows o consola (console) en el caso de UNIX o Linux. En dispositivos de red, como enrutadores o conmutadores, se habla comúnmente de terminal.
  • En UNIX y Linux se hablamos también de intérprete de comandos (command-line interpreter) para referirnos al programa que interpreta las instrucciones escritas -y no al programa donde se escriben.

La instrucción que se ejecuta en esta interfaz se compone de varios elementos. Veamos el siguiente ejemplo con el comando imaginario docx2pdf.exe que permite transformar archivos Word en formato PDF:

Aquí podemos distinguir:

  • Comando (command): Es la sentencia o programa que escribe el usuario. Los comandos pueden venir acompañados de otros elementos a los que denominamos, en su conjunto, argumentos (arguments). Los argumentos pueden ser opciones o parámetros.
  • Opciones (options): Son palabras reservadas que modifican el comportamiento del comando. En nuestro ejemplo la opción <images> modifica el tratamiento de imágenes.
  • Parámetros (parameters): Son los valores variables requeridos por el comando o las opciones. En el ejemplo anterior la opción <images> requiere como parámetro el valor sí (Y) o no (N).
  • Instrucción (instruction): Por lo general, al conjunto del comando y sus parámetros, lo denominamos instrucción. Cuando la instrucción se usa para manipular bases de datos, hablamos de sentencia (sentence).

Cuando nos referimos a alguno de estos elementos en el texto, es recomendable acompañar también cada elemento de su descripción. Si en el texto hacemos referencia a una opción, conviene utilizar la palabra opción. Por ejemplo, en la siguiente frase, el significado de <images> es ambiguo:

Sería mejor decir:

Otras normas que podemos usar son:

  • Los usuarios escriben (type) instrucciones. Ejemplo: Para convertir el archivo a formato PDF, escribe la siguiente instrucción.
  • Al moverse a un directorio en la interfaz en línea, indicamos que se accede a una ruta (path). Ejemplo: Para ejecutar el comando docx2pdf.exe, accede a la ruta C:\Doc2PDF\bin.

Estilo

Un requisito al documentar la interfaz en línea de comandos es que el texto de la instrucción destaque y sea claramente legible. De esta forma evitamos que el texto explicativo que acompaña a la instrucción se confunda con el texto que el usuario ha de escribir en pantalla. Además, queremos que la descripción de la instrucción sea lo más clara posible. La forma de conseguir esto varía de una documentación a otra, aunque se ha generalizado el uso de una caja de texto con un fondo destacado y una tipografía con caracteres de ancho fijo (como las tipografías Consolas o Courier):

El siguiente cuadro resume otros elementos de estilo que también se han estandarizado al documentar esta interfaz:

Si tenemos que hacer referencia a algún comando o argumento dentro de un párrafo, seguimos el mismo criterio, destacando este elemento con una tipografía de caracteres de ancho fijo y, siempre que nuestro editor nos lo permita, con un fondo distintivo. Por ejemplo:

Al describir la sintaxis de una instrucción en línea de comandos, es común añadir una descripción de las opciones que lo acompañan. Si el número de opciones es pequeño (3 o menos), podemos hacer esto en formato de lista, como en el siguiente ejemplo:

Si el número de opciones es mayor, es mejor estructurar la información en una tabla.

Para indicar el comando a ejecutar, basta con introducir la acción del usuario de la siguiente forma:

Podemos también omitir completamente la palabra instrucción, como ocurre en el siguiente ejemplo donde simplemente se indica escribe lo siguiente (type the following):

O incluso escribir en texto de forma más directa, omitiendo completamente la frase escribe lo siguiente, como se puede ver aquí:

Otras normas de estilo:

  • Cuando indicamos que un usuario escribe un comando, no es necesario añadir a continuación y presiona Enter (and press Enter)
  • Utilizamos dos puntos al final de la descripción y antes de mostrar el bloque de código, como hemos visto en los ejemplos anteriores.

La Guía de Estilo de IBM desarrolla extensamente estas y otras normas de estilo al documentar la interfaz de comandos. Sin querer llegar a ese nivel de detalle, este artículo busca ser una referencia rápida que, con una inversión mínima de tiempo, permita dotar de un estilo común y coherente a nuestra documentación.

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.