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.