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.