Simplificar las capturas de pantalla en documentación

En el estudio Cómo leen la web los usuarios (Nielsen Norman Group, 1997) se concluye: "[los usuarios] no leen la web. La gente rara vez lee páginas web palabra por palabra; por el contrario, escanean la página seleccionando palabras y oraciones individuales.” La documentación se ha adaptado progresivamente a esta realidad, con formatos de página mejor estructurados y un uso minimalista del lenguaje que apoya el flujo de lectura del usuario. Resulta llamativo que, en este proceso, el tratamiento de las capturas de pantalla apenas haya cambiado.

Qué nos enseña una aplicación de mapas

¿Qué vemos cuando abrimos Google Maps en nuestro teléfono móvil? Por defecto, la pantalla muestra una vista simplificada de nuestro entorno (imagen izquierda). Esta vista es una descripción esquemática (no real) del terreno, donde resulta fácil identificar los puntos de interés. Por el contrario, en la vista aérea del mapa (imagen derecha), se ofrece una imagen fiel del entorno, con abundantes elementos visuales, pero donde puede ser difícil determinar las áreas de interés (comercios, transporte público, monumentos, etc.) o la importancia relativa de unos elementos frente a otros.

Los mapas que utilizamos habitualmente resultan útiles en la medida en que ofrecen una visión simplificada del entorno. La vista aérea de un mapa puede ser interesante para hacernos una idea más precisa de la naturaleza del terreno, pero es poco eficaz cuando nuestro propósito es desplazarnos a un punto concreto del mapa.

El uso que hacemos hoy de las capturas de pantalla en la documentación técnica se asemeja mucho a la vista aérea de un mapa. Mostramos la interfaz de usuario (el terreno) en toda su complejidad y detalle. Y en muchos casos, la densidad de información de estas imágenes nos obliga a destacar elementos (ver figura) para centrar la atención en el punto de interés -reconociendo así la dificultad de “encontrar nuestro camino” en la imagen. El problema no es la captura de pantalla en sí misma, el problema es que su interpretación rompe el flujo de búsqueda de información del que habla Nielsen Norman Group en su estudio.


El coste de capturar pantallas

Incluso con los inconvenientes de interpretar estas imágenes, no hay duda de que añadir una captura de pantalla en la descripción de una tarea mejora su comprensión. El conocido refrán “una imagen vale más que mil palabras” se convierte casi en axioma en redacción técnica. Si la interfaz del software es poco intuitiva o usa métodos no convencionales para resolver una tarea, incorporar capturas de pantalla al texto resulta muchas veces imprescindible.

Este hecho contrasta con la escasez de ilustraciones y capturas de pantalla con la que muchos fabricantes de software acompañan los textos de ayuda. ¿Por qué esta contradición? La explicación es sencilla: la generación de estas capturas de pantalla supone un incremento importante del tiempo de desarrollo. Esto es especialmente visible cuando la documentación se publica en diferentes idiomas, y aunque existen soluciones que permiten automatizar (parcialmente) esta tarea, las variaciones dentro de un mismo programa y entre diferentes idiomas pueden hacer muy compleja la automatización. ¿Cómo podemos, entonces, proporcionar a la usuaria el soporte visual necesario, sin romper su flujo de búsqueda de información y sin incrementar el tiempo de desarrollo?


Ilustrar, no capturar

Si accedemos a la documentación del Centro de Aprendizaje de Google Suite podemos observar algo aparentemente anecdótico: las capturas de pantalla han sido sustituidas por ilustraciones simplificadas de la interfaz:

Estas ilustraciones solo muestran aquella parte de la interfaz que afecta a la tarea que se describe, el resto de elementos se minimizan o se obvian intencionadamente. Este hecho podría parecer puramente estético, pero tiendo a pensar que existen razones prácticas que llevan a Google a utilizar este método:
  • Reduccir los costes de producción
  • Mejorar la consulta de información

La reducción de costes solo puede entenderse cuando la documentación tiene que traducirse a varios idiomas y cuando el software se actualiza con relativa rapidez. Ambas condiciones se cumplen hoy en el caso de muchos productos de software -y se cumplen sin duda para los productos de Google tomados como ejemplo.

La mejora en la consulta de información existe porque la usuaria dispone solo de la información visual necesaria para realizar su tarea. Todos los elementos accesorios de la interfaz se eliminan o simplifican. Así, por ejemplo, los menús incluyen solo el texto que corresponde con las opciones descritas en la tarea. La lectura de estas imágenes es más sencilla, y soporta en mejor medida el flujo de búsqueda de información. En comparación con una captura de pantalla, las ilustraciones se asemejan a mapas simplificados del terreno en los que se ha eliminado todos los detalles superfluos.


Algunas estimaciones (no basadas en datos reales)

Hasta aquí todo parecen ventajas, ¿pero no supone también la generación de ilustraciones una tarea con un elevado coste? Es indudable. Sin entrar en el proceso detallado de traducción de estas ilustraciones (que requeriría una expliación mucho más extensa), la ventaja de utilizar ilustraciones reside en que solo necesitan hacerse una vez, y es relativamente sencillo traducirlas a múltiples idiomas. Por el contrario, las capturas de pantalla han de ser tomadas cada vez para cada idioma.

A continuación arrojo algunas estimaciones (no basadas en ningún dato real). Al trabajar en la primera versión de un manual que contiene múltiples capturas, se dan las siguientes circunstancias:
  • El tiempo o esfuerzo necesario para tomar las capturas de pantalla es bajo con pocas traducciones, pero aumenta de manera lineal al aumentar el número de traducciones.
  • El tiempo o esfuerzo necesario para crear las ilustraciones es alto inicialmente, pero se ve compensado con un menor esfuerzo en la traducción.
La situación de esta primera versión se puede ilustrar de la siguiente forma:
Existe un número de idiomas (punto C en la imagen), a partir del cual el coste de tomar capturas de pantalla es mayor que el coste de traducir las ilustraciones de forma automática. ¿Qué ocurre cuando el software se actualiza en una nueva versión? Cualquier actualización que afecta a la interfaz de usuario (nuevos menús, cambio en el esquema de colores, etc.) nos obliga al laborioso proceso de obtener de nuevo las capturas de pantalla. Las ilustraciones, precisamente por su sencillez, pueden ser adaptadas de forma mucho más rápida. En este caso tendríamos la siguiente situación:
El coste para tomar las capturas de pantalla se mantiene invariable, pero el coste inicial para generar las ilustraciones es ahora mucho menor que en la primera versión del software. El punto C a partir del cual resulta más eficiente usar ilustraciones se consigue ahora con un número más bajo de idiomas.

Si el fabricante de software dispone además de varios productos con una interfaz similar, las ilustraciones pueden ser reutilizadas en otros productos, multiplicando así el beneficio de usar ilustraciones en lugar de capturas de pantalla. En la siguiente imagen podemos ver un ejemplo de este caso, donde se utiliza la misma ilustración para definir una tarea en dos productos distintos:

Pero si solo tenemos en cuenta el factor tiempo/esfuerzo, estamos dejando de lado el argumento más importante para nuestra usuaria: estas ilustraciones simplificadas, al reducir el número de detalles visuales, soportan el proceso de búsqueda de información de manera más eficaz que las capturas de pantalla. Si el formato y texto del documento técnico han cambiado progresivamente hacia un enfoque más minimalista, quizá sea también el momento de aplicar este mismo enfoque a las capturas de pantalla.

Apple frente al Diseño Material

La ausencia de una propuesta coherente en el diseño de sus interfaces debe hacer reflexionar a Apple. Si la compañía aspira a que su software siga jugando un papel clave en la compra de sus dispositivos, tiene que hacer de la usabilidad de sus sistemas operativos y aplicaciones una prioridad.

La forma sigue a la función

MacOS, el sistema operativo originario de los ordenadores Macintosh, puso en escena ideas revolucionarias en un mundo dominado por la monotonía de los PCs y las pantallas monocromas. Años después, Apple volvería a marcar el pulso de la telefonía móvil con el lanzamiento del iPhone y el sistema operativo iOS. Movida por la necesidad de potenciar la venta de sus primeros modelos de iPhone -antes de que este dispositivo se convirtiera en un objeto omnipresente-, la compañía impulsó el desarrollo de aplicaciones e interfaces móviles, aportando soluciones a los problemas derivados de mostrar información en un espacio reducido. Este impulso innovador en el diseño de software parece hoy agotado.

Son varios los factores que permiten llegar a esta conclusión, pero el ejemplo más notable de este agotamiento es, sin duda, su servicio de música en línea Apple Music con su aplicación para dispositivos móviles del mismo nombre y las versiones más recientes de iTunes. Desde su aparición el pasado año, Apple Music ha sido ampliamente criticado en foros de usuarios y publicaciones especializadas por incorporar un diseño confuso y una usabilidad mediocre. Este hecho resulta especialmente llamativo en una compañía para la que la experiencia de usuario ha sido siempre una prioridad, y lo es aún más cuando hablamos de aplicaciones que son clave en la venta de servicios en línea.

A este factor hay que añadir lo que parece una pérdida de rumbo en el diseño de sus aplicaciones para móviles. Mientras que aplicaciones como Calendario mantienen su aspecto original, el rediseño de nuevas aplicaciones como Notas insiste en ideas pasadas como el skeumorfismo (dotar a las aplicaciones con la apariencia de objetos físicos, en este caso, la apariencia de papel), pero las combina torpemente con otras dando lugar a un resultado desigual. Fijémonos, por ejemplo, en el botón añadir (+). No es ya solo que los botones tengan aspectos y ubicación diferentes, sino que además la función que cumplen es distinta: añadir un nuevo evento al calendario en un caso y añadir un acción a una nota en el otro, y no una nueva nota como cabría de esperar. Estos ejemplos no son casos aislados. El ecosistema de aplicaciones en iOS es como un museo con obras de arte de gran belleza, pero donde los cuadros de arte abstracto se mezclan con los de arte barroco y resulta difícil entender el recorrido por las salas.

Apple parece haber renunciado a sus principios de usabilidad en favor del diseños efectistas que cumplen con la forma, pero no con la función. Sus interfaces, con fotografías muy cuidadas, un uso prominente de los espacios vacíos y tipografías de gran tamaño, no tienen una traducción clara en términos de usabilidad. Microsoft nos demostró con Metro que un diseño de interfaces atractivo es insuficiente si no se apoya en principios de uso claramente definidos. Metro, la iniciativa de diseño que hizo su aparición en el escritorio de Windows 8 y Windows Phone, introducía elementos novedosos en la interfaz de usuario a los que Microsoft no supo dotar de una identidad clara, y que prácticamente han desaparecido en las versiones más recientes de sus sistemas operativos.

El Diseño Material

En la creación de experiencias de usuario simples y atractivas Apple parecía ser la única respuesta, pero los esfuerzos realizados por Google durante los últimos dos años pueden cambiar esta tendencia. En el año 2014, durante su conferencia de desarrolladores Google I/O, Google presentó su iniciativa de diseño de interfaces Diseño Material (originalmente en inglés, Material Design). El objetivo de esta propuesta se describe así:

Crear un lenguaje visual que sintetiza los principios clásicos del buen diseño con la innovación y las posibilidades de la tecnología y la ciencia.

Esta iniciativa no es rupturista. No propone nuevos modelos sino que, basándose en conceptos asentados en el campo del diseño, establece unas líneas bien definidas para el desarrollo de una experiencia de usuario unificada, sin importar el tipo de aplicación o dispositivo. Como se ha señalado, esta propuesta no es necesariamente mejor, pero es bien cierto que el esfuerzo realizado por Google para promover el uso de sus principios materiales es enorme cuando lo comparamos con el de sus competidores. Artículos, guías de estilo, tutoriales y vídeos sobre Diseño Material inundan la red. Las charlas acerca de este tema cuentan con su propio espacio en la conferencia anual de desarrolladores de Google, y la página web donde se detallan los aspectos de esta iniciativa es rica en detalles y ejemplos de implementación. Esta abundancia de información contrasta con lo limitado de la guía de estilo de Apple para el desarrollo de interfaces en iOS.

La propuesta de Google pretende llegar a cada rincón del ecosistema Android, con la incorporación de un número creciente de aplicaciones móviles. Cada vez son más los desarrolladores que hacen uso de elementos característicos del Diseño Material como el panel deslizante, las tarjetas o el botón de acción superpuesto. Estos elementos no son arrojados al azar a la interfaz, muy al contrario, su ubicación, aspecto y comportamiento se basan en reglas bien establecidas. Las aplicaciones mejoran porque, como señala Meng To, cuando las reglas de estilo son estrictas es difícil salirse de ellas y hacerlo mal. Las aplicaciones muestran mayor coherencia sencillamente porque, al contrario de lo que ocurre con iOS, el desarrollador cuenta con más herramientas y mejor información.

Lo Material como estándar

Lejos de ser algo reducido al entorno del sistema operativo Android, los principios materiales se hacen también un hueco en las aplicaciones para iPhone y iPad. Google publica incluso guías para a aquellos desarrolladores que quieren trasladar sus aplicaciones entre uno y otro entorno manteniendo las señas de identidad de cada uno. En contra de lo que algunos analistas han criticado, Google no pretende imponer su estándar de Diseño Material en iOS, sino crear uno donde actualmente no existe.

En un momento en el que las aplicaciones de nuestros móviles incorporan cada vez más funcionalidades, la necesidad de un estándar es crucial. Para hacernos una idea de esta creciente complejidad, pensemos en la integración de Google Maps con Uber y servicios de Taxi o las inclusión de asistentes personales en servicios de mensajería como Facebook Messenger o Google Allo. Si bien es cierto que establecer un estándar en el diseño y usabilidad puede hacer las aplicaciones móviles más parecidas entre sí, esto no tiene por qué ser necesariamente aburrido. Tal y como apunta Michael Horton en su artículo de Wired, todas las aplicaciones comienzan a parecer la misma, pero esto no es algo malo si con ello se consigue simplificar la experiencia del usuario.

Pero el interés de Google en extender su iniciativa no finaliza en el móvil. Con la presentación de su proyecto Polymer, los principios materiales se trasladan a las aplicaciones web, permitiendo que los desarrolladores se centren en el creación de servicios y no de interfaces. De nuevo, este hecho contrasta con la ausencia de Apple en lo que a desarrollo web se refiere. Las aspiraciones por parte de esta compañía de hacer de la venta de servicios en la nube un eje de su negocio chocan con un aspecto pobre y excesivamente simplistas de aplicaciones web como iCloud Drive, Photos o las versión en línea de Pages, Numbers y Keynote.

Apple Watch y watchOS

La falta de unas directrices claras de diseño y usabilidad por parte de Apple están originando una fragmentación en iOS muy similar a la que existe todavía en el ecosistema Android. Cada desarrollador parece buscar la forma más original de interactuar con su aplicación, muchas veces en contra de lo que tiene sentido. Es precisamente esta disparidad de criterios la que ha minado durante años la evolución de Android, y a la que Google pretende hacer frente con su iniciativa material. Esta situación, unida a una presencia aún tímida de Apple en servicios web, puede hacer peligrar el atractivo que los dispositivos de la marca tienen para el consumidor. No podemos olvidar que Apple es fundamentalmente una compañía de hardware, y que su objetivo -como ha declarado su director ejecutivo Tim Cook en varias ocasiones- es el de usar el software como elemento conductor a la compra de dispositivos.

Pero no toda la esperanza está perdida. El sitio web para el diseño de interfaces con Apple Watch y watchOS -el sistema operativo que da vida al reloj inteligente de la compañía- muestra un notable esfuerzo por encontrar una forma coherente y eficaz de interactuar con este dispositivo. Quizás Apple, que en las últimas versiones de su sistema operativo de escritorio ha incorporado elementos propios del iPhone -Siri, como ejemplo más destacable-, pueda seguir el mismo principio con su reloj inteligente, utilizando watchOS como base para una renovación de su software móvil.

No estamos hablando aquí de implementar las soluciones adoptadas en un dispositivo de 3 pulgadas a una pantalla de un móvil o un ordenador, sino de adaptar y ampliar aquello que funciona a otros dispositivos, dotando a todo el ecosistema Apple de una identidad y uso común. Los cambios anunciados en su pasada conferencia mundial de desarrolladores parecen indicar una apuesta por trasladar elementos de usabilidad incorporados inicialmente en watchOS a iOS. El cambio en el centro de notificación, con alertas enriquecidas y el uso de tarjetas deslizantes en el centro de control, se asemejan notablemente al funcionamiento del reloj inteligente.


Pero esto no es suficiente. Apple debe definir con más y mejor información sus principios de diseño y usabilidad, poner en relieve la importancia de seguir estos principios y dotar a los desarrolladores de más herramientas. Es necesario además apoyar aquellas aplicaciones que hacen buen uso de estas normas (por ejemplo, dándoles un lugar relevante en su tienda de aplicaciones App Store) y ayudar económicamente a los desarrolladores más pequeños (por ejemplo, reduciendo las tarifas de acceso y comisiones de su Store), que no cuentan con la posibilidad de invertir en diseño y usabilidad.

(este artículo fue publicado originalmente en LinkedIn el 28 de Agosto de 2016)

Diseño Material y escritura técnica

El el año 2014, durante su conferencia de desarrolladores Google I/O, Google presentó su proyecto de Diseño Material (originalmente en inglés, Material Design). Esta iniciativa propone un marco de trabajo para desarrolladores que permita una experiencia de usuario común en cualquier aplicación y dispositivo. Pero la propuesta de Google, por su propia naturaleza, resulta interesante más allá del desarrollo de aplicaciones.

Hacia una práctica de lo Material

[El Diseño Material] tiene el potencial de ser una de las mejoras visuales más significativas de la web en general.

- (Armin Vit, Brand New / Under Consideration)

Tradicionalmente, el desarrollo de contenido documental ha tomado como base dos elementos fundamentales: tipología y estilo. La tipología define el modelo de información que sustenta el documento. Por ejemplo, DITA establece los tipos tarea, concepto y referencia como posibles modelos de información. El estilo es un elemento igualmente importante en documentación técnica. Gracias al estilo dotamos de una coherencia visual a la informació, algo clave para facilitar la exploración de contenido por parte del usuario.

Tipología y estilo nos permiten, por sí mismas, definir un tema acerca del cual informar o asistir al usuario, pero resultan insuficientes para establecer relaciones con otros temas y proporcionar una visión holística de la información. Las cuestiones que se plantean aquí son ¿pueden los usuarios, con un simple vistazo, descubrir la totalidad de la información que se presenta ante ellos?, ¿puede esta información adoptar formas que permitan identificar fácilmente un punto de partida y el curso de acciones requerido por la tarea?

En su Diseño Material, Google apuesta por unos principios básicos -pero claramente definidos- de aspecto y usabilidad que puedan hacerse extensivos a todo tipo de aplicaciones y plataformas. Pero lo más interesante de esta apuesta es que su desarrollo es lo suficientemente amplio como para poder aplicarla en otros campos; sin ir más lejos, el de la escritura técnica. Aplicar el Diseño Material a la documentación técnica, supondría dotar a esta de una experiencia de usuario común que no estuviese ligada a la concepción particular de cada fabricante de software, y serviría como elemento de relación entre distintos tipos de información. Pensemos por un momento: ¿tiene hoy sentido que la experiencia del lector ante un documento de ayuda sea distinta para cada fabricante de software e incluso para un mismo fabricante?

El Material es la metáfora

Una metáfora material es la teoría unificadora de un espacio racionalizado y un sistema de movimiento. El material se basa en la realidad táctil, inspirada en el estudio del papel y la tinta, pero tecnológicamente avanzados y abiertos a la imaginación y la magia. (fuente: Introduction to Material Design, Google design)
Para poder explicar la filosofía detrás del Diseño Material, Google introduce el concepto de quantum paper, un elemento similar al papel pero mucho más dinámico y transformable. Se toma así un elemento de uso común, el papel, y se le dota de características singulares. El papel se presenta de este modo como una metáfora de la información.

Resulta casi imposible no establecer aquí una relación entre el uso del papel como vehículo de la información y la documentación técnica. Incluso después de trasladar la documentación de usuario a la web en sus diferentes concepciones, uno de los formatos más comunes sigue siendo PDF, una representación electrónica de un libro. La documentación, independientemente de su formato, sigue utilizando el concepto originario del papel como elemento a partir del cual estructurar la información. El Diseño Material propone transformar este elemento y amplificar sus capacidades de interacción con el usuario o, en nuestro caso, con el lector.

Las dimensiones de lo material como niveles de información

El Material tiene dimensiones X e Y variables y un grosor uniforme. (fuente: Material properties, Google design)

Esta hoja de papel cuántico puede transformarse dinámicamente para adaptar su tamaño a la información que se muestra. Del mismo modo que podemos doblar y desdoblar una hoja de papel, la información puede también expandirse para adaptarse al medio y a la audiencia. Si tomamos una hoja de papel y la doblamos por la mitad, dispondremos de una superficie más limitada para mostrar información, pero que puede ser suficiente para que el usuario complete su tarea. Dada la necesidad, podemos desdoblar la hoja dando la posibilidad al lector de acceder a información extendida.

El hecho de que el material no pueda expandirse en profundidad tiene también un significado en el tratamiento de la documentación. Los artículos técnicos deben de ser relevantes para la tarea del lector, mostrando la información necesaria, pero no más. La información -el material- crece ricamente ligado entre sí, bien expandiéndose cuando nos mantenemos en el mismo plano de información, o bien mediante enlaces, cuando necesitamos pasar a un plano distinto.

Múltiples elementos materiales no pueden ocupar el mismo punto en el espacio simultáneamente. (fuente: Material properties, Google design)

Otra característica de lo Material es que dos elementos no pueden ocupar simultáneamente el mismo espacio físico. De forma análoga, dos bloques de información independientes no deben describir lo mismo. Cada elemento cumple una función para el usuario y la separación entre el contenido de uno y otro ha de ser clara.

División y fusión de lo Material

Divide los casos de usuario complejos, amplios o vagos en actividades más pequeñas. Estas tareas más pequeñas pueden reutilizarse, ser más fáciles de entender o cumplir mejor los objetivos del usuario. (fuente: Navigation, Google design)

El material dividido puede unirse. (fuente: Material properties, Google design)
La división y fusión de lo material encuentran de nuevo su equivalencia en la división y fusión de la información. Deconstruir un elemento nos ayuda a entender mejor el conjunto a través de sus partes. Igualmente, la información se divide para hacerse más comprensible, y también para ser más fácilmente reutilizable en otros niveles. La información puede dividirse y combinarse de muy distintas formas, y puede también fusionarse llegado el caso.

Los conceptos de división y fusión son la base de la documentación estructurada, en la que un tema es dividido en elementos menores, que a su vez están construidos con bloques de información marcados semánticamente.

Las sombras como enlaces

Las sombras proporcionan importantes pistas visuales acerca de la profundidad de los objetos y el movimiento. Son la única señal visual que indica la separación entre las superficies. (fuente: Elevation and shadows, Google design)
Una de los elementos más destacadas del Diseño Material es el empleo profuso de sombras para separar materiales. Al igual que ocurre en el mundo real, los componentes del mundo Material proyectan sombras sobre un plano, tanto más profundas cuanto mayor es su elevación sobre el mismo. Visualmente las sobras nos permiten saber cómo se establece la relación entre los distintos materiales. Estas sombras equivalen a hiperenlaces en el área de la información. Los enlaces establecen un punto de unión -y también de ruptura- entre la información a uno y otro nivel. Cada enlace permite al usuario trasladarse a un plano de información inmediato y diferente.

El movimiento como jerarquía

El movimiento proporciona:
- Una guía focalizada entre vistas.
- Relaciones jerárquicas y espaciales entre los elementos.
- [...]

(fuente: Motion, Google design)
El movimiento de los elementos y la definición de planos son el fundamento de lo Material. Las interfaces utilizan el movimiento para dar respuesta a las acciones del usuario y destacar aquello que requieren su atención. El movimiento permite también establecer una relación y jerarquía entre los distintos elementos. En el campo de la escritura técnica, la tabla de contenidos (en sus distintas variantes) permite establecer las relaciones de jerarquía entre los distintos bloques de información. Pero esta tabla de contenidos es un componente estático que por sí mismo no resuelve los problemas derivados de la exploración de contenido, especialmente en artículos técnicos de una cierta complejidad y extensión. Las tablas de contenido dinámicas (como las que podemos ver en el siguiente ejemplo tomado de la documentación de Google Docs), junto con el uso de las tarjetas, aportan una solución novedosa a esta cuestión.

Las tarjetas como puntos de acceso a la información

Las tarjetas proporcionan contexto y un punto de acceso a una información más completa. (fuente: Cards, Google design)

Las tarjetas se están imponiendo en el diseño de aplicaciones móviles como el elemento más efectivo para dar entrada a la información. Google ha estado trabajando con estas tarjetas desde hace algún tiempo, y otros fabricantes están también adoptando este modelo. En el aspecto documental, las tarjetas nos ayudan a sintetizar la tabla de contenidos en sus elementos más básicos, proporcionan al usuario un curso de acciones lógico para realizar su tarea y son un punto de entrada a niveles de información superiores.

La documentación de producto muestra hoy en día un aspecto dispar, donde cada fabricante se esfuerza por aplicar soluciones particulares a problemas comunes. El Diseño Material propone un marco de actuación que trasciende el desarrollo de aplicaciones y con capacidad para convertirse en el elemento común en la experiencia de los usuarios con la documentación.

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.

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.