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.

El manual no es un hotfix

La documentación de software es un recurso esencial para el usuario -tanto más cuanto mayor es la complejidad de ese software-, pero que el propio usuario entiende como su último recurso. Desde esta observación resulta fácil comprender por qué la solución a los errores de un producto de software tienen que darse en el propio producto y no en su documentación.

La escritura no puede solucionar el mal diseño

En su artículo Writing can’t fix bad design (La escritura no puede solucionar el mal diseño), Beth Aitman muestra el ejemplo de una puerta automática con un mecanismo de cierre tan confuso que se acompaña de instrucciones para su manejo. La autora utiliza este ejemplo para explicar por qué cuando el diseño de un producto no es acertado la solución no es explicar cómo usarlo. La solución es arreglar el diseño. Basta con prestar un poco de atención a nuestro alrededor para descubrir casos similares donde el diseño enrevesado de un objeto se intenta solucionar arrojando información al usuario. Desde parquímetros con un largo listado de instrucciones de uso hasta puertas donde nunca parece estar claro el sentido de giro, el mundo está lleno de ejemplos de mal diseño.


No solo coincido plenamente con el análisis de la autora, sino que además creo que el mismo argumento se puede trasladar fácilmente a un producto de software y a los errores que se derivan de su desarrollo. Si exceptuamos los problemas graves (por ejemplo, de seguridad) donde la velocidad para informar a los usuarios es crucial, dar solución a un problema con un producto en un documento no es una buena opción.

Y no hablamos solo de errores en el código, que afectan al funcionamiento del programa, sino también de aquellos que afectan a su uso. Porque una usabilidad mediocre quizá no nos impida continuar con nuestra tarea, pero puede dificultarnos innecesariamente la misma, como ocurre cuando la disposición de botones en una interfaz no sigue un orden lógico y nos obliga a pararnos para entender su funcionamiento. Esto es lo que en desarrollo de software se ha dado en llamar error estético -un nombre desafortunado, porque reduce la usabilidad a un aspecto puramente ornamental.

La gente lee novelas

La gente lee novelas. No lee documentación. -Mark Baker
En el momento de utilizar un programa de software por primera vez, el usuario no recurre a la documentación, sino que intenta descubrir el funcionamiento del mismo basándose en su experiencia previa con programas similares y en las indicaciones que le da la interfaz. Normalmente, el usuario solo recurre a la documentación en dos situaciones: cuando encuentra un error o cuando no es capaz de completar una tarea. Para el usuario la documentación es un recurso necesario, pero es siempre su último recurso.

Si entendemos esta idea de último recurso, no nos costará entender por qué el manual no es el lugar indicado para resolver errores de software o de diseño. Si una interfaz no es intuitiva y dificulta completar una tarea, añadir una explicación al manual es una solución, pero no satisface las necesidades del usuario y lo que es peor, disminuye su percepción sobre la calidad del producto. Cubrir las deficiencias de un programa en el manual puede parecer inicialmente una solución más rápida y económica que desarrollar un parche (hotfix), pero a la larga puede salir cara.

Por qué documentar

Si un buen diseño simplifica el uso de un software cabe preguntarse, ¿sigue siendo necesario acompañarlo de un manual? Invertir en la usabilidad de una aplicación no solo incide positivamente en su calidad final, además reduce la dependencia del usuario en el manual. Pero a partir de un determinado nivel de complejidad, consultar la documentación resulta inevitable. En aplicaciones como las que tenemos instaladas en nuestros teléfonos móviles no se espera que hagamos uso de un manual de instrucciones. Son aplicaciones sencillas que cumplen una única finalidad y donde las instrucciones se limitan a una pequeña introducción durante el primer uso o consejos (tooltips) para familiarizarnos con los controles en pantalla.


Pero en el mundo fuera de nuestros teléfonos no todo resulta tan sencillo. Pensemos por un momento en un paquete de software de ofimática o de diseño gráfico. Estas aplicaciones no solo son más complejas de usar, también más complejas de desarrollar, aumentando la posibilidad de encontrarnos con errores. Y es que todos entendemos que no es lo mismo el mecanismo de apertura de la puerta de casa que de la compuerta de un avión -la del avión es más compleja y viene acompañada de instrucciones.

En otros casos la documentación es fundamental para explicar no tanto cómo funciona una aplicación, sino cuál es el conjunto de tareas que debemos completar en ella. Una cosa es que un programa de software sea fácil de usar y nos permita realizar las tareas sin demasiadas complicaciones y otra muy distinta que entendamos qué tareas se espera que realicemos y en qué orden. La documentación tiene un papel esencial explicando procesos, y no solo interfaces

Si los fabricantes de software quieren evitar la frustración de sus usuarios es imprescindible que dediquen recursos a mejorar la usabilidad y reducir los errores. Pero cuando los errores -inevitablemente- aparecen, es necesario solucionarlos en el producto, y no en el manual. Porque el usuario no quiere leer manuales o descifrar interfaces, quiere completar su tarea.

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)

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.


La nueva herramienta documental de StackOverflow convierte el ejemplo en protagonista

Documentation, la nueva herramienta documental de StackOverflow, busca extender el mecanismo de preguntas y respuestas que popularizó el sitio web al terreno de la redacción técnica. Esta fórmula, de por sí innovadora, resulta aún más atractiva al convertir los ejemplos en protagonistas de cada artículo, relegando a un segundo plano el desarrollo teórico de cada concepto.

Preguntas, respuestas… y documentos

StackOverflow presentó esta semana Documentation, definida en el propio blog del sitio web como el mayor cambio de la plataforma desde su lanzamiento. StackOverflow fue fundado en el año 2008 para expandir el conocimiento de los desarrolladores, independientemente de cuál fuese su lenguaje de programación. Este sitio web adquirió notoriedad rápidamente gracias a un sistema de preguntas y respuestas por el que las respuestas más útiles son votadas por la comunidad, consiguiendo que destaquen sobre aquellas menos útiles. A este sistema de clasificación por votos, se añade además un componente de ludificación basado en puntos de reputación que se otorgan a los usuarios más activos y con mayor número de votos positivos. Desde su fundación, millones de desarrolladores -y no desarrolladores- se han beneficiado de esta plataforma para resolver sus dudas.


Este mecanismo de preguntas y respuestas ha mejorado progresivamente, convirtiéndose en el modelo de referencia para muchos otros sitios web. Pero este planteamiento tiene también sus limitaciones. Una de ellas es que las preguntas tienden a ser muy específicas, o relativas a problemas de programación muy concretos, dejando de lado cuestiones de carácter más general, que son sobre todo comunes entre los principiantes. De hecho, muchas preguntas son rápidamente moderadas -descartadas- por ser demasiado genéricas. La nueva herramienta de documentación busca poner fin a esta limitación, sirviendo de base para tratar un contenido de carácter más académico y, por definición, con un alcance más extenso.

Documentation da cabida a una gran cantidad de buen contenido que ha sido rechazado, o que es difícil de “hacer bien” en el formato de preguntas y respuestas. A saber, la referencia aceptada, general, el contenido didáctico.

Mostrar mejor que contar

Pero, ¿qué hace del planteamiento de StackOverflow algo novedoso cuando se compara con otras plataformas documentales? Desde un punto de vista puramente formal, Documentation podría pasar por otra wiki en la que el contenido se desarrolla con la participación conjunta de diferentes personas. Lejos de ser así, la fórmula de StackOverflow es radicalmente diferenciadora.

Por un lado, el modelo de preguntas y respuestas se traslada ahora al terreno de la documentación técnica, de manera que los artículos con más votos positivos prevalecen sobre los menos votados. En la práctica, esto se traduce en que los artículos y ejemplos más útiles destacan sobre el resto y pasan a convertirse así en comúnmente aceptados. De esta forma, la autoridad del redactor técnico sobre un tema queda relegada a la suma de decisiones de la comunidad, que es finalmente quién evalúa qué contenido es útil y cuál no lo es. Este modelo de desarrollo no es tanto una colaboración de diferentes partes -como sucede con una wiki-, sino la competencia de esas partes, a través del sistema de votos, por proporcionar el mejor contenido.

Juntos, creemos que podemos hacer lo mismo para la documentación técnica que lo que hicimos para las preguntas y respuestas

Por otro lado, situar el ejemplo como elementos principal del artículo supone romper con el modelo clásico de documentación técnica, donde estos ejemplos quedan subordinados al desarrollo teórico de cada concepto. Los ejemplos dejan de ser así meros elementos de apoyo. Se enfatiza además la necesidad de que cada artículo de Documentation contenga varios ejemplos, y que estos, de la misma forma que se hace con el formato de preguntas y respuestas, puedan ser votados.


Este tratamiento de los ejemplos es innovador, pero al mismo tiempo lógico en lo que a documentación técnica se refiere. En la mayoría de las ocasiones, un ejemplo ilustra mucho mejor cómo usar una funcionalidad del código que una exposición teórica sobre esa funcionalidad. Sin embargo, es dudoso que este planteamiento sea también el más adecuado en documentación técnica no destinada a desarrolladores, donde las explicaciones son esenciales para que el usuario entienda las tareas que ha de completar.

A esta iniciativa se unen ya otros desarrolladores como Microsoft, que participarán aportando y revisando el contenido, y usando ese contenido para ampliar su propia documentación. La propuesta de StackOverflow está en sintonía con los cambios anunciados recientemente por Microsoft, con una clara tendencia a situar los ejemplos y tutoriales como ejes de la documentación técnica.

Iniciativas como la llevada a cabo por StackOverflow, de alguna forma, ponen también en cuestión el extenso sector editorial de los libros de aprendizaje para programadores. De igual forma que el modelo libre y colaborativo de Wikipedia puso fin a las tradicionales enciclopedias, el desarrollo de un modelo de documentación libre y colaborativo, puede también suponer el final de una buena parte de este sector. Si el punto de partida para aprender un lenguaje de programación hace tan solo unos años pasaba por la la compra de uno o más libros, la tendencia hoy parece inclinarse por aprender a través del conocimiento compartido por otros, y el uso extensivo de tutoriales (ejemplos, al fin y al cabo) como base del aprendizaje.

Documentation, aún en fase beta, incluye ya una gran cantidad de artículos [link:http://stackoverflow.com/documentation] tan solo unos días después de su lanzamiento, lo que demuestra el enorme interés de la comunidad de desarrolladores por participar de esta idea y compartir su conocimiento más allá del modelo de preguntas y respuestas.

(este artículo fue publicado originalmente en LinkedIn el 24 de Julio 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.

¿Son los bots el futuro de la documentación?

Una nueva generación de asistentes virtuales pretende revolucionar la manera en la que nos relacionamos con nuestros dispositivos y usamos las aplicaciones de cada día. ¿Serán también estos asistentes el futuro de los manuales de usuario? ¿Podrán algún día ayudarnos a utilizar programas y completar tareas complejas?

Clipo, el asistente virtual que Microsoft incorporó en Office 97 para eliminarlo solo unos años después, ha pasado a la historia como una de las peores ideas en software y usabilidad. Clipo -o Clippy, como se le conocía en inglés- fue un intento fallido de dar solución a dos problemas que, a día de hoy, se mantienen: el software es cada vez más complejo y los usuarios, independientemente de su nivel de conocimientos técnicos, no suelen acudir a la documentación para resolver sus dudas.

Son varios los factores que contribuyeron al fracaso de Clipo, pero uno de ellos fue, sin duda, que el conjunto de respuestas ofrecidas por el asistente era muy limitado. Clipo se empeñaba en ayudarnos a escribir cartas fuese cual fuese nuestra intención delante del ordenador, y se recreaba en explicarnos las listas numeradas una y otra vez. Clipo se presentaba como un asistente inteligente en una década en la que la inteligencia artificial era aún más ficción que ciencia. El rechazo masivo de los usuarios de Office, y la generalización de internet y los foros de ayuda de usuarios, acabaron con el malogrado clip.

El texto es la interfaz

En los años 90, animados por el crecimiento tecnológico y la expansión de las redes de conexión digital, los operadores de telefonía nos mostraban un futuro no muy lejano en el que las videollamadas con familiares y amigos estarían a la orden del día. Hablar por teléfono o enviar mensajes de texto SMS parecía sólo un peaje necesario hacia una era de comunicación más moderna y visual.

Pero como ocurre con tantas otras predicciones, que imaginan el futuro como un desarrollo lineal de la tecnología sin considerar otros factores, la realidad ha resultado bien distinta. La mensajería -el texto- y no el vídeo -la imagen- está siendo el eje transformador de la comunicación. El crecimiento de la mensajería instantánea pilló con el paso cambiado a los grandes operadores de telefonía, que siempre consideraron a los SMS como el hermano pobre de las comunicaciones y no supieron reaccionar a tiempo a la explosión de aplicaciones como WhatsApp.

Hay varias razones que justifican hoy este hecho -en defensa de las operadoras, casi todas difíciles de predecir hace solo unos años-, como la omnipresencia de las comunicaciones móviles, que hacen de la conversación en texto un medio mucho más adecuado y fluido que la imagen. O como la conveniencia del texto en países donde un desarrollo precario de las redes de datos no deja muchas más opciones.

Esta época dorada de la mensajería instantánea viene acompañada de un resurgir en el campo de la inteligencia artificial, con nuevos servicios que integran lo mejor de cada área. Y es que la evolución en la mensajería instantánea no afecta solo a las comunicaciones interpersonales, sino también a nuestra comunicación con las máquinas. La robótica ha visto grandes avances en las últimas décadas, pero no ha conseguido crear robots con los que comunicarse sea creíble. La mensajería instantánea, al reducir la interfaz de nuestro interlocutor a simple texto, permite una comunicación sujeto-máquina mucho más natural. Este hecho viene explicado por la Teoría de la Respuesta Social, en la que el desarrollo de interfaces con características humanas nos hace considerar a las máquinas como otro actor social más. Esta teoría cobra ahora más relevancia que nunca.

La era de los bots

Una de las grandes novedades anunciadas por Facebook en su conferencia de desarrolladores F8 del pasado mes de Abril, fue la aparición de asistentes en su servicio de mensajería instantánea Messenger. Estos asistentes funcionan como pequeñas aplicaciones dentro del propio programa que nos permiten completar ciertas tareas, como reservar una mesa en un restaurante, comprar ropa o elegir el ramo de flores más adecuado para ese ser querido. En el futuro, más y más empresas añadirán estos asistentes virtuales o bots (como se les ha dado en bautizar) a Facebook Messenger.

Tampoco resulta extraño que Google anunciara hace solo unos días Allo, un nuevo servicio de mensajería inteligente en el que los usuarios podrían hacer preguntas y resolver distintas cuestiones, o ser asistidos por el programa en diferentes tareas. La coincidencia de intereses de estos dos grandes de internet por la mensajería instantánea y la inteligencia artificial no es anecdótica.

Como han señalado ya varios medios, el propósito de empresas como Facebook y Google con estos productos está claramente ligado -como no podía ser de otro modo- a sus intereses comerciales. El objetivo es proporcionar a los consumidores toda una variedad de servicios dentro de una misma aplicación -la suya-, evitando que tengan que abandonarla para completar una tarea, y manteniéndolos así el mayor tiempo posible dentro en la aplicación. En otras palabras, obtener más información acerca de los gustos del consumidor y exponerlo a publicidad durante más tiempo.

Pero, en definitiva, ¿qué son estos bots? Bot, al igual que cloud, es un concepto abstracto que nos ayuda a entender mejor las cosas. En esencia, un bot es un motor de lenguaje natural conectado a un programa de inteligencia artificial capaz de procesar nuestras palabras y aprender nuestros hábitos. Este elemento obtiene respuestas mediante la comunicación con otras redes y aplicaciones. Las APIs -componentes de software especializados- son la base de esta comunicación.


Estas iniciativas se apoyan en avances cada vez más significativos en inteligencia artificial. No es anecdótico que Lee Se-dol, considerado como uno de los mejores jugadores de Go de todos los tiempos, fuera derrotado el pasado mes de Marzo por el programa de inteligencia artificial DeepMind desarrollado por Google. Ser maestro de Go, un juego de tablero milenario con una complejidad superior al ajedrez, no solo requiere años de estudio y práctica, sino una buena dosis de intuición. La derrota del coreano marca un precedente en un juego de estrategia considerado hasta no hace mucho sólo apto para humanos.

El contenido es el formato

En contra de lo que comúnmente se piensa, la documentación de software no es un mundo estático e impermeable a los avances tecnológicos. Con el paso del tiempo, los manuales físicos que acompañaban a los programas se convirtieron en libros electrónicos, con contenido poco o nada enlazado y funcionalidades de búsqueda sencillas. Estos dieron paso a su vez a la documentación más común hoy en día, basada en plataformas web con contenido enlazado y capacidades de búsqueda más potentes.

A la vista de los avances en inteligencia artificial y de una presencia creciente de la mensajería instantánea en nuestras vidas cabe preguntarse, ¿son los bots el futuro de la documentación técnica?, ¿buscarán los usuarios del mañana un Clipo más inteligente, capaz no solo de responder a un conjunto de preguntas preestablecidas sino un amplio abanico de cuestiones? Y si es así, ¿cuál será el aspecto de esta documentación el día de mañana?

La aparición de bots documentales permitiría a los usuarios resolver sus consultas mientras completan una tarea, sin necesidad de saber a qué manual acudir o qué artículo de ayuda consultar. La ayuda en pantalla que incorporan algunas aplicaciones nos permite ya acceder a preguntas frecuentes sobre la tarea que realizamos, y suponen un primer paso en esta dirección. Si la tendencia parece ser la integración de interfaces de texto con mecanismos de inteligencia artificial cada vez más potentes, la documentación ha de saber aprovechar esta tendencia.


Pero para hacer de estos bots documentales una realidad deben darse tres circunstancias. En primer lugar, los escritores técnicos debemos desarrollar un contenido -aún- más estructurado, donde la semántica tenga un papel principal. Iniciativas como DITA pueden ser claves en este desarrollo. En segundo lugar, el contenido ha de estar ricamente enlazado, evitando bloques de información aislados. Lo importante es crear relaciones entre estos bloques de información, y no tanto estructurarlos con un criterio que será siempre arbitrario. Por último, los gestores de contenido deben abrirse a estos motores de inteligencia artificial, permitiendo el acceso a la información relevante, y eliminando así la necesidad de publicar el contenido en un formato determinado. En la era de los bots, el contenido es el formato.


(Este artículo fue originalmente publicado en LinkedIn el 27 de Mayo de 2016)

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.