tag:www.funcion1.com,2013:/posts Función1 2018-09-26T10:02:01Z Jorge Pérez Campo tag:www.funcion1.com,2013:Post/1325205 2018-09-24T20:32:40Z 2018-09-26T10:02:01Z 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.
]]>
Jorge Pérez Campo
tag:www.funcion1.com,2013:Post/1314589 2018-08-24T07:33:32Z 2018-08-31T04:32:09Z Canalizaciones compartidas en documentación técnica
El pasado día hablaba con uno de los responsables de nuestro departamento de Documentación sobre el futuro de la redacción técnica. El buen clima y el buen café en la terraza de la oficina animaron un interesante intercambio de ideas. Pero me quedo sobre todo con algo que él comentó:
Creo que no hay una herramienta en el mercado que pueda dar una solución completa a la gestión documental de una organización. No importa el negocio o los requerimientos de esa organización, siempre faltará algo. Estoy convencido de que la solución pasa por la integración de diferentes herramientas y fuentes de información.

Esta idea resonó en mi cabeza varios días después del encuentro. Desde hace tiempo tiendo a creer que el planteamiento de una única herramienta o metodología para la gestión documental es fallido. Este hecho es especialmente visible en entornos complejos y de gran tamaño, con múltiples equipos integrados en el desarrollo documental. Los gestores de contenido (CMS) han intentado ofrecer la solución, pero en muchos casos han complicado aún más los procesos sin dejar contento a nadie. Hace más de un año tuiteaba al respecto:


Pocos días después, por simple casualidad, me encontré con este interesante artículo de Sarah O'Keefe (@sarahokeefe), relacionado con la misma idea: Single-sourcing is dead. Long live shared pipes! O’Keefe plantea aquí el concepto de las canalizaciones compartidas (shared pipes, en el artículo original en Inglés):
[...] hemos intentado crear un mundo en el que todos los autores trabajan en un único entorno [...] La premisa es que, de alguna manera, tenemos que conducir a todos hacia el Único y Verdadero Método de Trabajo.

Pero hoy en día tenemos un entorno complejo con multitud de sitios para crear, almacenar y administrar contenido. Cada proveedor de software promueve una forma distinta de hacer las cosas.

En un entorno de canalizaciones compartidas, todo el contenido puede usar los mismos flujos de trabajo de representación y localización, pero con diversos formatos de origen y herramientas de creación.

Creo que es fácil entender este concepto si pensamos en la forma en la que muchas compañías de software comercializan sus apps: aplicaciones sencillas que realizan una única función, pero que a su vez se conectan a otras apps para presentar la información unificada.

Pensemos en Trello, por ejemplo. Trello no pretende dar respuesta a todas las necesidades del usuario, como pueden ser mensajería instantánea, videoconferencias, gestión de ficheros, etc. Por el contrario, Trello desempeña una única función (administrar tarjetas en un tablero Kanban virtual) en la que es excelente, y complementa su función mediante la integración con otros sistemas (Slack, Hangouts, Drive, etc.). Esta integración es posible gracias a las APIs, que cumplen la función de canalizaciones y permiten la conexión entre sistemas de software dispares. Trello coordina y da sentido a estas fuentes de información, pero en realidad no controla ninguna de ellas. Del mismo modo, el modelo de canalizaciones compartidas huye de la solución monolítica y busca integrar a todas las partes del proyecto documental.


Como señala O’Keefe en su artículo, quizá ha llegado el momento de dejar de pensar en el Único y Verdadero Método de Trabajo y comenzar a pensar en un flujo de trabajo compuesto por diferentes orígenes, actores y herramientas. El reto pasa ahora por conseguir conectar y coordinar cada uno de estos canales.

]]>
Jorge Pérez Campo
tag:www.funcion1.com,2013:Post/1256700 2018-03-04T13:12:33Z 2018-08-27T13:15:44Z docs.microsoft.com y el futuro de la documentación técnica

Si hubo un tema en el mundo de la redacción técnica que ocupó blogs y discusiones de Twitter en 2017 este fue, sin duda, Docs Like Code. Esta metodología, promovida inicialmente por Patrick Arlt (@patrickarlt) y desarrollada después por Anne Gentle (@annegentle), plantea un tratamiento de la documentación técnica con las mimas herramientas y métodos aplicados en el desarrollo de software. La atención suscitada por este nuevo planteamiento resulta llamativa en un espacio tan poco dado al cambio como el de la redacción técnica.

docs.microsoft.com

Y sin duda el ejemplo más destacado en la adopción de Docs Like Code es Microsoft, con su nueva plataforma documental docs.microsoft.com. La importancia de Microsoft no es solo cualitativa, por lo que el fabricante de Redmon representa en el ámbito tecnológico, es también cuantitativa, si tenemos en cuentas la cantidad y diversidad de documentación que desarrolla.

Tradicionalmente, la documentación técnica se ha asentado en los siguientes puntos:
  1. El desarrollo de contenido estructurado (encabezado por iniciativas como DITA).
  2. El uso de XML, como lenguaje para dar soporte a este contenido.
  3. La adopción de gestores de contenido, para su transformación y tratamiento.

docs.microsoft.com supone un cambio fundamental a este modelo -llamémoslo tradicional-, con una apuesta por artículos ligeramente estructurados, Markdown como lenguaje y GitHub como gestor de la información.

Si el paso del manual de usuario impreso al manual electrónico y de este al formato web son el resultado de sucesivos avances tecnológicos, el paso a este nuevo modelo documental solo puede explicarse por la irrupción de una nueva tecnología. Pero antes de entrar en ello, conviene repasar algunos conceptos.

Contenido estructurado

Explicar de qué hablamos cuando hablamos de contenido estructurado no es fácil. Esta dificultad radica en que “estructurado” es un concepto que ha cambiado considerablemente a lo largo del tiempo. Antes de la generalización del ordenador personal, todo contenido conforme a un cierto patrón podía considerarse como estructurado. Pensemos por ejemplo, en una receta de cocina donde, con pocas variaciones, se sigue una misma estructura: dificultad de la receta, tiempo de preparación, ingredientes y pasos.

Con la generalización del ordenador personal se presenta la necesidad de que el contenido pueda ser procesado por máquinas, con el objetivo de transformarlo e intercambiarlo más fácilmente con otras máquinas. Ya no basta con usar una sencilla plantilla de trabajo, es necesario que esta plantilla y las normas sean más rígidas, para que el contenido sea más uniforme y más fácilmente procesable por las máquinas (algoritmos, para ser más exactos).

Los escritores técnicos comenzamos así a escribir el contenido dentro de complejas plantillas, donde cada elemento (una lista, una tabla, un párrafo, una imagen, etc.) está perfectamente identificado y delimitado. El resultado es un contenido rigurosamente estructurado y que evita cualquier tipo de ambigüedad, facilitando su tratamiento y transformación por medios digitales.

XML

XML se convierte en el lenguaje de marcas que da soporte a este modelo de redacción técnica con un contenido altamente estructurado. Se dice que es un lenguaje de marcas porque emplea una serie de elementos, que diferenciamos con los símbolos < y >, para definir el contenido. Estas marcas representan la meta-información o semántica del contenido; en otras palabras, información sobre la información. Tomemos el siguiente ejemplo donde se describe una tarea usando el lenguaje XML:
Como se puede ver, la información de la tarea se mezcla con marcas que definen qué representa cada elemento, pero que hacen tremendamente difícil la lectura del texto.

Gestores de contenido

XML no fue diseñado para ser utilizado como lenguaje de escritura. Los textos escritos en XML son difíciles de leer o editar directamente. El que haya sido adoptado como lengua franca en documentación técnica se explica sólo por la necesidad de automatizar el tratamiento del contenido por máquinas.

Esta complejidad, inherente a XML, hace a su vez difícil gestionar la información escrita en este lenguaje. Como solución a este problema, hace varios años comenzó a popularizarse el uso de Gestores de Contenido (conocidos normalmente por su siglas en Inglés CMS, o Content Management Server). El gestor de contenido es, en síntesis, una base de datos en la que se almacenan y clasifican fragmentos de texto XML, y donde se automatiza el tratamiento de la información.

Hacia un nuevo modelo

Es innegable que XML, el lenguaje estructurado y los gestores de contenido han facilitado el avance de la redacción técnica, pero también lo es que este avance corre paralelo a una mayor complejidad en el tratamiento de la información. Estas tecnologías han hecho el contenido más fácil de procesar para las máquinas pero, al mismo tiempo, más difícil de procesar por las personas. La promesa de los gestores de contenido como solución a esta complejidad no siempre se ha visto cumplida. En este contexto no resulta extraño que empresas como Microsoft abandonen el modelo de gestión tradicional.

Por un lado, en docs.microsoft.com, Microsoft sustituye el uso de XML por Markdown, un lenguaje de marcas ligero cuyo uso y popularidad no ha dejado de crecer en los últimos años. La principal ventaja de Markdown es su sencillez y legibilidad. Hay que tener en cuenta que leer o escribir un texto en XML resulta muy complejo. La redacción en XML se apoya en programas especializados que ocultan las etiquetas del lenguaje, y la revisión de textos requiere su transformación a un formato intermedio (como PDF) que pueda ser interpretado por el revisor. Este hecho se traduce en numerosas horas de trabajo para transformar el fichero XML y ajustar el resultado final. No es extraño que muchos redactores técnicos tengan la sensación de trabajar más tiempo en transformar documentos que en la mejora de su contenido. La sencillez de Markdown rompe con este esquema y permite al redactor hacer un uso más eficiente de su tiempo.

Una de las principales críticas al uso de Markdown en documentación técnica es que carece de capacidades semánticas. Es decir, no podemos definir, como hacemos con las etiquetas en XML, la meta-información del contenido. La consecuencia inmediata es que no es posible trabajar de forma estructurada (en sentido estricto) con Markdown. Del mismo modo, tampoco existe la necesidad de trabajar con un gestor de contenido tradicional. Esto permite a Microsoft optar en docs.microsoft.com por una gestión simplificada del contenido, donde los ficheros se organizan en la plataforma de desarrollo GitHub siguiendo una estructura simple de carpetas, muy similar a lo que podemos encontrar en nuestro ordenador. Se diría que Microsoft da un paso atrás, al ignorar los procesos establecidos y probados en documentación técnica. Personalmente, creo que este es un paso muy calculado.

Google y la inteligencia artificial

Si buscamos imágenes del término “flor” en Google, el resultado será un enorme listado de fotos de flores. Esto no deja de ser obvio. Pero pensemos en ello por un momento. ¿Qué hace que esto sea posible?

El contenido que existe en internet no se encuentra meticulosamente clasificado con etiquetas que permiten identificarlo como una flor o como cualquier otro objeto. De hecho, es difícil imaginar un contenido más dispar y desestructurado que la web. Clasificar el contenido de internet con reglas de procesamiento estrictas resulta imposible. La única forma de enseñar a Google qué es una flor, es exponiendo este motor de búsqueda a muchas imágenes de flores, y asociando esas imágenes al término “flor”. Las máquinas han empezado así a aprender conceptos del mismo modo que nosotros: por asociación y repetición. Esto es, en síntesis, a lo que llamamos inteligencia artificial.

Durante años los seres humanos nos hemos dedicado a modelar la información para que pudiera ser fácilmente procesada por las máquinas. Pero mientras nos afanábamos en esta tarea, las máquinas han aprendido a adquirir conocimiento como humanos a mayor velocidad. El comunicador Mark Baker (@mbakeranalecta) explica de forma excepcional esta idea en su artículo Quality in Structured Writing.

La inteligencia artificial no es solo una nueva tecnología que mejora y sustituye a la anterior; es un cambio tecnológico fundamental que transformará nuestra manera de relacionarnos con las máquinas. Este es, precisamente, el salto tecnológico que permite a Microsoft el paso de un modelo de redacción técnica tradicional, al modelo Docs Like Code. Si las máquinas parecen haber desarrollado capacidades avanzadas para interpretar el contenido no estructurado que les ofrecemos, ¿qué sentido tiene seguir invirtiendo cantidades enormes de tiempo en estructurar ese contenido?

Tiendo a pensar -es una mera especulación- que Microsoft hizo este razonamiento durante el desarrollo de docs.microsoft.com. ¿Es XML un lenguaje más potente y robusto que Markdown? Sin duda. ¿Son los gestores de contenido herramientas que facilitan las tareas documentales? Absolutamente. ¿Es la escritura estructurada clave para el tratamiento eficaz de la información? Cierto. Todas estas son soluciones válidas, pero su justificación pierde fuerza cuando las máquinas comienzan a razonar como nosotros y, en ocasiones, mejor que nosotros.

Usuarios que escriben

Visto con el prisma de la Inteligencia Artificial, la adopción de un modelo documental Docs Like Code parece un paso lógico para Microsoft. Pero esta no es la única razón. Uno de los objetivos de docs.microsoft.com es hacer accesible la documentación al usuario final, permitiendo que este proponga cambios o mejoras o, incluso, que añada nuevo contenido.

Los gestores de contenido, el lenguaje estructurado y XML son herramientas especializadas que requieren de un conocimiento fuera del alcance del usuario final. En la práctica, la participación del usuario en el desarrollo de la documentación resulta imposible con el modelo tradicional. La simplicidad del modelo Docs Like Code, por contra, fomenta esta participación al simplificar todo el proceso de autoría. En palabras del comunicador y redactor técnico Tom Johnson (@tomjohnson):

No resulta práctico pedirle a las personas de la comunidad -que no son escritores técnicos y que no tienen las herramientas y conocimientos necesarios- que escriban en formatos estructurados. Tomar contribución de las masas requiere que simplifiques tu modelo de autoría. Termina convirtiéndose en una elección. O tomas la ruta de creación de contenido estructurado o tomas la ruta de la colaboración.

El crecimiento del número de artículos en docs.micrsoft.com, y la incorporación continua de mejoras, parecen indicar que Microsoft ha dado con las solución correcta. Una solución que simplifica enormemente el desarrollo y gestión de la documentación técnica, que permite al redactor centrarse en la mejora del contenido y la incorporación continua de cambios, y que ofrece al usuario final un canal de participación accesible durante todo el proceso.

]]>
Jorge Pérez Campo
tag:www.funcion1.com,2013:Post/1227702 2018-01-07T10:39:00Z 2018-01-12T11:56:51Z Documentación sin fricción

En marketing, fricción se define como la resistencia psicológica del consumidor a realizar una compra. Los consumidores queremos obtener el producto deseado, pero sin vernos obligados a un tedioso proceso para ello. Una página web poco intuitiva o una larga cola de clientes en un mostrador pueden echar atrás a un comprador inicialmente convencido. De igual forma, los usuarios buscan poder resolver sus dudas en el manejo de herramientas, pero -cada vez más- sin recurrir al manual de instrucciones.

El manual

“Los usuarios no leen documentación”. Esta afirmación, muy popular entre los redactores técnicos es, sin embargo, incompleta. Como señala el comunicador Mark Baker en su artículo Usersʼ Advocate: Nobody Reads Documentation, los usuarios no leen documentación, de la misma forma que tampoco leen recetas de cocina o diccionarios. Los usuarios consultan:

Hay una gran diferencia entre consultar una fuente de información y leerla. La lectura puede tomar horas o días. La consulta lleva minutos o segundos. La lectura requiere tiempo para la actividad de leer. La consulta tiene lugar en el contexto de otra actividad.

Pero consultar la documentación obliga, en cualquier caso, a detener la tarea que llevamos a cabo para realizar la consulta. Si la ayuda no está integrada en el producto, nos encontramos con el problema añadido de encontrarla. No resulta extraño que todos recurramos a Google o al compañero más cercano para resolver nuestras dudas. 

Pensemos por un momento en la última vez que apareció un error en el panel de nuestro electrodoméstico o el salpicadero del coche. ¿Cuál fue nuestra primera reacción? Google. Consultar internet para resolver una duda se ha convertido ya en un acto reflejo. Y si no obtenemos una respuesta satisfactoria, la mayoría de nosotros contactará con el servicio técnico. Buscar información sobre el error en el manual es siempre nuestra última opción.

Consumidores y fricción

Pero, ¿por qué ocurre esto? En marketing se habla de puntos de fricción para analizar los factores que se interponen entre el consumidor y la adquisición de un producto o servicio. La fricción puede tener un origen interno (nuestra conciencia recordándonos que no podemos permitirnos ese coche nuevo) o externo (una larga cola en el supermercado). Cuantos menos puntos de fricción, más posibilidades de compra. 

Las empresas conocen bien este hecho, y buscan eliminar -o reducir- la fricción proporcionando a los clientes la mejor experiencia de compra posible. No es casualidad que aquellas empresas que mejor entienden estos factores sean líderes en su sector. Veamos solo unos ejemplos que nos ayudarán a entender mejor este concepto:

Amazon. Mediante el uso de su botón “1-click”, Amazon elimina instantáneamente el tedioso proceso de completar nuestros detalles durante el pedido (dirección, forma de pago, método de envío, etc.). Pero Amazon va más allá en este proceso, con lo la posibilidad de pedir productos con nuestra voz usando el asistente Alexa, o usar un simple botón físico para, de manera instantánea, hacer la compra del detergente o el papel higiénico.

Apple. La calidad y la atención por el detalle y el diseño de los productos de Apple es difícil de cuestionar. Pero para muchos consumidores estos factores no justifican el alto precio que es necesario pagar para adquirir estos productos. Apple conoce este hecho, y por ello ofrece la posibilidad de ver y tocar sus productos en las diferentes tiendas físicas Apple Store repartidas por todo el mundo (unas 500 en la actualidad). Esta posibilidad, junto con una experiencia de compra cuidada y un entorno que permite experimentar libremente con el producto, reducen considerablemente la oposición inicial del comprador. 

Uber. Independientemente del dilema ético que a muchos nos supone usar Uber, el éxito de este servicio de transporte privado es innegable. En muchas capitales del mundo, Uber es ya el medio de trasporte privado por defecto. Como señala Scott Galloway (@profgalloway) en su libro “The Four”, el éxito de Uber no se debe a su sofisticado sistema de seguimiento por GPS, ni tampoco al menor coste del servicio en comparación con un taxi tradicional, sino a la facilidad de pago. El coste se carga automáticamente usando el método de pago seleccionado en la aplicación, sin que sea necesario buscar monedas y billetes apresuradamente en la oscuridad del asiento de atrás.

El momento del pago es un punto de fricción frecuente. Empresas como Uber han sabido entenderlo; otras fallan estrepitosamente. Un buen ejemplo son las compañías aéreas: ¿por qué tengo que pagar en el momento de pedir un café durante un vuelo si la compañía aérea tiene ya todos mis datos (asiento, nombre, dirección de correo electrónico, tarjeta de crédito)?

Documentación sin fricción

Los redactores técnicos podemos aprender mucho de las estrategias empleadas por estas empresas. Si la fricción es la barrera que separa a nuestros usuarios de la documentación, la solución no puede ser otra que buscar fórmulas que la hagan más accesible. Planteo aquí algunas de estas fórmulas. 

Internet

Señalar la importancia de tener la documentación en formato web en internet puede sonar fuera de lugar en 2018. Pero es sorprendente la cantidad de productos que carecen de una documentación publicada en formato accesible, como HTML. Merece la pena recordar que tener la documentación en internet no significa colgar un manual en PDF en una página web.

Internet es ya (desde hace tiempo) el medio en que todos nos movemos y nuestros teléfonos móviles, el vehículo para navegar en él. Disponer de la documentación de un producto en internet, de forma accesible, es el mínimo exigible a cualquier fabricante.

Ayuda integrada y contextual

Pero no basta con que la ayuda esté en en internet. Si el usuario ha de abandonar su medio de trabajo para consultar la documentación, estamos añadiendo un punto de fricción. En este sentido, es fundamental integrar el manual en el uso del producto. En resumen, llevar la ayuda al usuario y no al revés.

La ayuda tiene que ser, además, sensible al contexto. En otras palabras, capaz de responder a las acciones que se desarrollan en la pantalla. La ayuda contextual mostrada por herramientas como Google Sheets o Smartsheet cuando editamos una fórmula es un buen ejemplo de esto. Integración y contextualización son las claves.

Ayuda multicanal

Los redactores técnicos seguimos pensando en la documentación en términos de formato (PDF, Word, HTML, etc.) y no en términos de medio, olvidando la importancia de que la información sea accesible desde cualquier lugar donde el usuario desarrolla su tarea. Para el trabajador de una fábrica este medio puede ser un manual físico, para el empleado de oficina puede ser internet, y para la enfermera que asiste un paciente en un domicilio, el teléfono móvil.

Un ejemplo de esto lo tenemos en la cadena de cosméticos Sephora. Sephora brinda a sus clientas una experiencia de compra multicanal, donde la tienda actúa como el espacio lúdico, pero donde la posibilidad de probar, reservar y pagar el producto se puede realizar desde distintos medios: página web, aplicación para el móvil o un chatbot integrado en un programa de mensajería como Messenger.  Sephora ha sabido entender que la forma más eficaz de llegar a sus clientas es estando disponible donde ellas centran su ocio. Y ese ocio se desarrolla (cada vez más) en la pantalla de nuestro teléfono móvil.

Realidad aumentada

La realidad aumentada (conocida por las siglas en inglés AR, de Augmented Reality) no es un concepto nuevo, como tampoco lo es su aplicación en la documentación técnica. Pero esta tecnología no ha sido una realidad palpable hasta hace pocos meses. La razón es simple: la tecnología necesaria aún no estaba disponible. La novedad es que ahora esta tecnología, limitada inicialmente a entornos muy concretos y con un alto coste de producción, se ha generalizado.

Gracias a la realidad aumentada (no confundir con la realidad virtual) nuestro teléfono móvil puede reconocer los elementos del mundo real (dimensiones, distancia entre objetos, iluminación, etc.) y superponer en este objetos no reales. Un buen ejemplo de esto es la aplicación de Ikea, que nos permite probar cómo quedarían los muebles en casa.

En 2017 Apple presentó ARKit, un conjunto de herramientas mediante las cuales los desarrolladores pueden crear aplicaciones de realidad aumentada para dispositivos iOS. Pocos meses después Google hizo lo propio con ARCore, destinado al desarrollo de aplicaciones Android. Estas herramientas, junto con los teléfonos móviles de última generación, ponen esta tecnología en nuestros bolsillos.

La realidad aumentada brinda posibilidades de asistencia y formación al usuario que no habían sido posibles hasta el momento. Pensemos por un momento en la capacidad de enfocar un objeto con nuestro teléfono móvil o tableta y obtener una visualización superpuesta de la ayuda para cada una de sus partes.

Chatbots

En el artículo ¿Son los bots el futuro de la documentación? hablé ya de las posibilidades que los asistentes conversacionales (o chatbots) ofrecen para comunicar con el usuario en su propio lenguaje y medio. Estoy convencido de que los chatbots, junto con la realidad aumentada, tendrán un papel clave en la documentación de productos de software y productos físicos respectivamente.

Un buen ejemplo de la aplicación de estos dos elementos lo encontramos (de nuevo) en Sephora. Desde las aplicaciones de esta cadena de cosmética, las clientas pueden conversar con un chatbot para obtener información sobre productos, reservar una sesión de maquillaje o pedir recomendaciones acerca de los colores más apropiados para el tono de piel. Sephora brinda también la posibilidad de probar los productos directamente en la aplicación, a través de una interfaz de realidad aumentada que emplea reconocimiento facial.

Empresas como Sephora, Amazon o Uber han entendido que eliminar fricciones es la clave para facilitar el acceso a un producto o servicio. Los redactores técnicos debemos de entender los puntos de fricción generados por la documentación, y realizar la transformación necesaria. Si no lo hacemos, corremos el riesgo de que la documentación deje de ser relevante. O peor, que el usuario abandone nuestro producto en favor de otra empresa que sí ha llevado a cabo esta transformación. 

]]>
Jorge Pérez Campo
tag:www.funcion1.com,2013:Post/1190125 2017-09-10T13:56:49Z 2017-09-10T13:56:50Z The Cathedral and the Bazaar

The shift towards agile software development models, with continuous integration processes and publication of new features, forces us as technical writers to review our own working methods. Leaving behind the model imposed by the traditional CMS and integrating documentation tasks into the development cycle is now more necessary than ever.

The Cathedral and the Bazaar

In 1999, Eric S. Raymond, one of the leading representatives of the open source initiative, published his essay entitled The Cathedral and the Bazaar. In this popular essay, Raymond writes about his experiences during the development of open code software, at the same time as he encourages programmers and companies to embrace this work philosophy.

Raymond uses the concepts of cathedral and bazaar to exemplify two quite distinct development models. The cathedral represents the development of proprietary software, where the source code is only accessible to a small group of programmers. The bazaar, on the other hand, represents the development of open source software, where the code is accessible to collaborators. The rigidity of a cathedral stands as a metaphor for a closed, centralized system, whereas the dynamism of a bazaar represents an open, collaborative system. Raymond maintains that the possibility of incorporating improvements and eliminating errors is much more extensive in a collaborative model than in a centralized one. The conclusion is that the software resulting from a collaborative model has fewer errors and is necessarily of higher quality.


The thesis explored in The Cathedral and the Bazaar has given rise to lots of discussions among those defending and criticizing open source software. The collaborative model is not free from problems, but offers advantages that make it attractive to many software development companies. It is not unusual to see such companies looking nowadays for formulas enabling them to adopt their own open source methodologies without renouncing their control of the code and intellectual property over the same.

In parallel, software development tools are incorporating more and more features that enable the principles of collaborative development to be extended to teams of workers. Together with this, the process of continuous integration and continuous delivery (known by the initials CI/CD) enables new features to be rolled out and errors to be resolved relatively quickly. Suffice to think just about the frequency with which many of the apps on our mobile telephones are updated.

The problem with content management systems

It is strange to see how this change in development methodologies has had scant repercussion on software documentation. This field continues to be founded on tasks of drafting, review, and publication that, in essence, have changed little in recent years. For writing, XML is still the standard markup language. More often than not, reviewing is still done using PDF files or, even worse, over email. And publication, which has gradually shifted to the web, often requires hours of adjustments to generate the correct PDF or HTML file.

This workflow is today sustained by complex Content Management Systems (CMS) that aim to solve the documentation needs of many different organizations at one fell swoop, but end up not entirely solving the needs of any of them.


But the fundamental problem lies in the fact that a traditional CMS understands the drafting, review, and publication tasks as actions that follow each other in orderly fashion over time and not, as so often seen in experience, all at the same time. An added problem is that the possibility of incorporating improvements from collaborators is limited to the review phase, with the documentation effectively ring-fenced for most of its development cycle.

“Ditch your CMS”

In 2014, Patrick Arlt (@patrickarlt), in the context of the Write the Docs conferences, gave a presentation titled Ditch Your CMS With Git and Static Site Generators. In this presentation, Arlt advocates abandoning the use of content management systems in favour of open code tools that favour collaboration and reduce the complexity oy documentation project.

A year later, in April, 2015, Anne Gentle (@annegentle) described the documentation process adopted by the OpenStack software manufacturer in her article entitled Git and GitHub for open source documentation. The model proposed by Gentle (subsequently developed in greater detail in her book Docs like code) proposes that technical writers should work alongside the development teams, adopting their same tools and methodologies. Because, if a software’s documentation is an integral part of the product and is produced in parallel, isn’t it more consistent to use the same workflows? In this new paradigm, writing documentation is not that different from writing code.

In summary, the Docs like Code methodology proposes:

  • Ditching the use of traditional CMS systems in favour of collaborative tools like GitHub (a code repository very popular with developers).
  • Adopting lightweight markup languages, abandoning complex languages like XML. The best-known example of these languages is Markdown.
  • Incorporating continuous review processes where reviewers can record changes at any time using pull-request mechanisms offered by GitHub.
  • Publishing product documentation regularly through the use of static page generators that enable the texts in Markdown format to be transformed into HTML code.

GitHub

Millions of developers all over the world use GitHub as the repository for their application code. But what makes GitHub such an attractive environment for amateur coders, independent developers and companies? The commercial success of GitHub has been born out of its ability to simplify the use of the Git tool (a software utility originally created to manage the development of Linux) in an easy-to-use web interface. In addition, GitHub facilitates the collaboration of multiple people on the same project in a relatively straightforward way. The complexity and scalability needs of modern software have made this feature essential.

Yet this change in software development methods is not so far away from what is happening in the documentation arena. While a manual was the responsibility of a single technical writer in the past, nowadays, with growing technological complexity and the constant integration of changes, the final result requires collaboration and co-ordination involving multiple individuals. The cathedral model imposed by content management systems has not been able to respond to this change.

The time has come

Far from being a mere concept, Docs like Code is also a reality for software companies as important as Microsoft, Amazon, or Twitter. In May, 2016, Jeff Sandquist (@jeffsandannounced Microsoft’s new documentation platform docs.microsoft.com in the following terms:
All documentation is designed to allow community contributions. Every article has an Edit button that takes you to the source Markdown file in GitHub where you can easily submit a pull request to fix or improve content.
A large part of the manufacturer’s documentation is already located on this new documentation platform in a clear wager in favour of the adoption of open systems. Other companies such as Amazon have followed this trend and it is now possible to see an “Edit on GitHub” button on many of the articles intended for developers.



In an article on the I’d Rather Be Writing blog, the specialist in documentation and technical writer Tom Johnson wrote a comment that goes to the root of the problem of using CMS:

No more black boxes that handle your content. No more expensive, proprietary systems to submit to. No more impossible-to-adjust-outputs. You can integrate it all simply, easily, and inexpensively.

The enormous influence these companies have in the world of software will, sooner or later, bring about the adoption of open bazaar-type documentation models to the detriment of rigid cathedral-type models. If effective and agile software development is the result of a collaborative process of continuous integration and publication, then documentation projects must necessarily adapt to this new reality.

(This article was originally published in Spanish and translated into English)

]]>
Jorge Pérez Campo
tag:www.funcion1.com,2013:Post/1186843 2017-08-27T15:14:25Z 2018-07-21T07:09:33Z ¿Es LinkedIn prescindible?

“Hay mucho talento fuera de LinkedIn”. Así resumía mi buen amigo José Manuel su experiencia con esta plataforma para profesionales en una conversación reciente. Esta afirmación no pasaría de un simple comentario si no fuera porque muchos -entre los que me incluyo- encontramos cada vez menos razones para participar en esta red.

Misión frente a realidad

LinkedIn, con más de 500 millones de usuarios, se define en su página Sobre nosotros como “la mayor red profesional del mundo”. Junto a esta afirmación, podemos leer:
Nuestra misión es sencilla: conectar a los profesionales del mundo para ayudarles a aumentar su productividad y rendimiento. Al unirte a LinkedIn obtienes acceso a personas, empleos, noticias, actualizaciones e información que te ayudará a destacar en tu campo profesional.
Pero basta un simple vistazo a esta plataforma para comprobar que la realidad dista mucho de esta noble misión. Y es que lejos de ser una red profesional, LinkedIn se ha convertido en una red social más. El problema fundamental es que en esa socialización LinkedIn está dejando de ser relevante para su masa de usuarios. Estas son solo algunas de las razones que ponen en evidencia la pérdida de valor del portal:

Las conexiones son irrelevantes. Las sugerencias de contactos se basan fundamentalmente en personas de nuestra propia empresa o de empresas en las que hemos trabajado anteriormente, pero resulta mucho más difícil encontrar contactos de nuestra profesión en otras empresas (algo sin duda mucho más interesante). Ocurre además que tras establecer una conexión de interés, rara vez se produce un intercambio de experiencias o ideas, precisamente porque la plataforma no ofrece ningún medio para ello. ¿El resultado? un simple engorde del número de conexiones sin ninguna utilidad real.

El sector tecnológico lo es todo. LinkedIn se ha posicionado claramente como una red para profesionales de IT. La explicación es sencilla si tenemos en cuenta el nuevo auge del sector tecnológico, con una demanda cada vez mayor de desarrolladores. Este factor se traduce en un número creciente de visitas (en otras palabras, impactos publicitarios) a contenidos y ofertas de este sector, relegando a un segundo plano al resto de contenidos.

Sin conexiones las publicaciones no tienen repercusión. LinkedIn da relevancia a los artículos y publicaciones de aquellas personas con mayor número de conexiones. Este hecho resulta obvio, pero tiene como consecuencia una pérdida del diferencial profesional de la red. La razón es que muchos usuarios buscan establecer conexiones con el único objetivo de incrementar el impacto de sus publicaciones, echando por tierra el valor profesional de estas conexiones, y de la plataforma en general.

El contenido de valor es casi inexistente. Si dejamos de lado las frases inspiradoras y célebres -repetidas hasta la saciedad-, los enlaces de autobombo, o las noticias que pueden encontrarse en cualquier otro sitio, los artículos jugosos o las actualizaciones que merecen la pena son casi inexistentes.

Instagramificación de la plataforma. En un intento por atraer un público más joven, LinkedIn ha introducido recientemente cambios que pretenden hacer más social su uso. El nuevo diseño, la aparición de las actualizaciones de estado, la incorporación de vídeo en directo o la ventana persistente de chat son muestras de ello. Pero es dudoso que LinkedIn consiga con esta estrategia atraer a un público más joven sin alienar su base existente de usuarios.


Titulitis y postureo. Estos son solo algunos de los títulos que podemos encontrar en esta red: Digital Transformer, Motivational Coach, Inno-Líder, Profesional 360°, Líder coach, Impulsor del bienestar integral, Über Tech Lead, etc.

Es difícil expresar la vergüenza ajena que provoca ver estos títulos en personas que -estoy seguro- son perfectamente válidas para realizar su trabajo, pero que no han dudado ni un instante en sumarse a la espiral de titulitis que inunda esta red. Lamentablemente, esta competición por el título más original esconde en no pocos casos la inseguridad de quien lo usa. Tampoco podemos pasar por alto el postureo de mostrar en el perfil un largo listado de grupos en los que jamás hemos hecho una aportación.

Me ahorro aquí muchas otras razones por las que pienso que el beneficio que se obtiene de LinkedIn es muy cuestionable, como el valor nulo de los endorsements, o una configuración de las opciones de privacidad intencionadamente abierta y confusa que consigue justo lo contrario: la falta de privacidad.

Peligros

Pero si LinkedIn fuese solo eso, una red social más, no pasaría de un entretenimiento inocuo. Lejos de ser así, nuestra presencia (activa o pasiva) conlleva ciertos riesgos:

Privacidad. Exponemos una gran cantidad de información personal, sin que quede claro quién es el destinatario de esta información y qué uso se hace de ella. La sentencia resuelta recientemente por un tribunal de EE.UU. a favor de una empresa que comercia con nuestros datos en LinkedIn, pone en evidencia este peligro.

Sexismo. Las actitudes sexistas contra las mujeres dentro de la plataforma se están convirtiendo en habituales, y no son pocas las que reciben solicitudes de contacto con fines no profesionales. La orientación de este portal hacia el sector tecnológico (donde los hombres son una abundante mayoría) solo puede acrecentar este problema. Los últimos cambios en la red, con un giro evidente a lo social, no parecen ser la forma más adecuada de atajar un sexismo rampante.

Distracción. Las alertas sobre visitas a nuestro perfil, las actualizaciones de nuestra red de contactos y un largo etcétera de notificaciones, disminuyen nuestra capacidad de atención y concentración. Y lo que es peor, ponen en peligro nuestro propio desarrollo profesional. Como indica Carl Newport (autor de títulos como So good they can’t ignore you o Deep work) “el valor en la nueva Economía no está en nuestro número de seguidores o likes, sino en la capacidad para enfocarnos intensamente en nuestro trabajo y ofrecer un valor único”.

“¿Qué hacen los cazatalentos en LinkedIn?”

Una vez más, José Manuel daba en la diana con esta pregunta durante nuestra conversación. Y es que si el valor de la plataforma es dudoso para los candidatos, resulta aún más difícil entender qué hace un cazatalentos en LinkedIn. Antes de LinkedIn y la popularización de las redes sociales, estos profesionales creaban una base de datos de perfiles. El cazatalentos funcionaba así como un curator de los candidatos más adecuados para las distintas ofertas de cada cliente, alimentando su base de datos con nuevos candidatos y manteniendo reuniones para conocer mejor las inquietudes profesionales y objetivos de los mismos.

LinkedIn se ha convertido hoy en esa base de datos, y las reuniones han dado paso al envío indiscriminado de mensajes desde las cuentas Premium de la plataforma. El listado casi infinito de posibles candidatos y la facilidad para contactar con ellos hacen de LinkedIn la solución más lógica. Pero si todo se reduce a dar de alta una cuenta Premium y usar las capacidades avanzadas de búsqueda y envío de mensajes, ¿para qué necesito contratar a una empresa de cazatalentos? ¿Cuál es el valor añadido? Bajo este nuevo paradigma, el cazatalentos ha pasado a convertirse en un intermediario, y si hay algo nos ha enseñado internet es que los intermediarios son prescindibles y quien sobrevive es quien aporta un valor añadido.

Maury Hanigan (@rethinkhiring), en su artículo How LinkedIn Fundamentally Ruined Recruitmentexplica en más detalle esta situación y apunta:

Lo que falta en la contratación en la era de LinkedIn es la conexión personal. Fue la profunda comprensión de los candidatos lo que hizo a los cazatalentos tan exitosos.

¿Qué hago yo en LinkedIn?

La mayoría de nosotros pensamos que mantener nuestra red activa nos deparará, más tarde o más temprano, el trabajo o proyecto soñado. Pero las posibilidades de que esto ocurra son extremadamente remotas. Si echo la vista atrás, me doy cuenta de que los cambios que han marcado mi carrera profesional han sido siempre fruto de una interacción en la vida real con otras personas. Los conocidos (o conocidos de conocidos) son casi siempre las casualidades que nos llevan a nuestro siguiente empleo o proyecto. No creo que LinkedIn sea una herramienta inútil, pero sí estoy convencido de que es un medio al que otorgamos mucha más importancia y tiempo del que merece.

Volviendo a la pregunta que abre este artículo, ¿es LinkedIn prescindible? Mi conclusión es que no es imprescindible. Si buscamos en Google una persona o empresa, es muy probable que uno de los primeros resultados sea un enlace a LinkedIn. Si estoy en una situación de búsqueda de empleo o pretendo dar a conocer mi empresa al mundo, desaprovechar el posicionamiento de esta plataforma en los motores de búsqueda carece de sentido. En cualquier otra circunstancia creo que su utilidad es muy limitada.

¿Puede LinkedIn convertirse en una red profesional verdaderamente útil? No pondría mis esperanzas en ello. Los cambios incorporados recientemente a la plataforma están claramente dirigidos a los millennials, que no parecen encontrar razones para crear o mantener un perfil en esta red. Es probable que estos cambios se traduzcan en una mayor cuota de usuarios a medio plazo, pero sin duda convertirán a LinkedIn un servicio aún más irrelevante. Los usuarios de mi generación (+40) ven cada vez menos sentido en este posicionamiento hacia lo social, y los más jóvenes necesitan establecer conexiones reales que les permitan acceder al mundo laboral y progresar en su carrera, no una mala copia de Facebook.

]]>
Jorge Pérez Campo
tag:www.funcion1.com,2013:Post/1174780 2017-07-18T17:05:30Z 2017-08-09T16:27:44Z La catedral y el bazar

El cambio hacia modelos de desarrollo de software ágiles, con procesos continuos de integración y publicación de nuevas funcionalidades, nos obliga como redactores técnicos a revisar nuestros propios métodos de trabajo. Abandonar el modelo impuesto por el gestor de contenidos tradicional e integrar las tareas documentales en el ciclo de desarrollo es ahora más necesario que nunca.

La catedral y el bazar

En 1999, Eric S. Raymond -uno de los principales representantes de la iniciativa de código abierto- publicó su ensayo La Catedral y el Bazar. En este popular ensayo, Raymond relata su experiencia durante el desarrollo de software de código abierto, a la vez que anima a los programadores y empresas a adoptar esta filosofía de trabajo.

Raymond utiliza los conceptos de catedral y bazar para ejemplificar dos modelos de desarrollo bien diferenciados. La catedral representa el desarrollo de software propietario, donde el código fuente es accesible solo a un reducido grupo de programadores. Por el contrario, el bazar representa el desarrollo de software de código abierto, donde el código es accesible a colaboradores. La rigidez de una catedral sirve de metáfora de un sistema cerrado y centralizado, mientras que el dinamismo de un bazar representa un sistema abierto y colaborativo. Raymond defiende que la posibilidad de incorporar mejoras y eliminar errores es mucho más amplia en un modelo colaborativo que en uno centralizado. La conclusión es que el software resultante de un modelo colaborativo incorpora menos errores y es, necesariamente, de mayor calidad.


La tesis expuesta en La Catedral y el Bazar ha sido motivo de discusión entre defensores y detractores del software de código abierto. El modelo colaborativo no está exento de problemas, pero ofrece ventajas que lo hacen atractivo para muchas empresas de desarrollo. No resulta extraño ver cómo estas empresas buscan hoy fórmulas que les permitan adoptar metodologías propias del código abierto sin renunciar al control del código y de la propiedad intelectual del mismo.

Paralelamente, las herramientas de desarrollo de software incorporan cada vez más funcionalidades que permiten llevar los principios de desarrollo colaborativo a los equipos de trabajo. Unido a esto, el proceso de integración y entrega continua (conocido por las siglas en inglés CI/CD, o continuous integration/continuous deployment) permite publicar nuevas funcionalidades y solucionar errores con relativa rapidez. Pensemos solo en la frecuencia con la que se actualizan muchas de las apps en nuestros teléfonos móviles.

El problema con los gestores de contenido

Resulta extraño ver cómo este cambio en las metodologías de desarrollo ha tenido escasa repercusión en la documentación de software. Este campo sigue asentado en tareas de redacción, revisión y publicación que, en esencia, han cambiado poco en los últimos años. En la escritura, XML sigue siendo el lenguaje de marcado estándar. La revisión en muchos casos se realiza aún mediante archivos PDF o, lo que es peor, a través del correo electrónico. La publicación, que progresivamente ha pasado al medio web, requiere en muchos casos de horas de ajustes para generar el archivo PDF o HTML correcto.

Este flujo de trabajo está hoy sustentando por gestores de contenido (conocidos por las siglas en inglés, CMS) complejos, que pretenden resolver las necesidades documentales de muchas organizaciones a la vez, pero que terminan por no resolver enteramente las necesidades de ninguna.


Pero el problema fundamental reside en que el gestor de contenidos tradicional entiende las tareas de redacción, revisión y publicación como acciones que se suceden ordenadamente en el tiempo y no, como demuestra la experiencia, de forma conjunta. Como problema añadido, la posibilidad de incorporar mejoras por parte de los colaboradores está limitada a la fase de revisión, quedando la documentación efectivamente cerrada durante la mayor parte de su ciclo de desarrollo.

"Tira tu CMS"

En el año 2014 Patrick Arlt (@patrickarlt), en el marco de las conferencias Write the Docs, realizó la presentación Tira tu CMS (titulada originalmente Ditch Your CMS With Git and Static Site Generators). Arlt plantea en esta presentación abandonar el uso de gestores de contenido en favor de herramientas de código libre que favorecen la colaboración y reducen la complejidad del proyecto documental.

Un año después, en Abril de 2015, Anne Gentle (@annegentle), describía el proceso documental adoptado por el fabricante de software OpenStack en su artículo Git y GitHub para una documentación fuente abierta (originalmente, Git and GitHub for open source documentation). El modelo propuesto por Gentle -que posteriormente desarrollaría con más detalle en su libro Docs like code- propone al redactor técnico trabajar de manera conjunta con los equipos de desarrollo, adoptando las metodologías y herramientas de estos equipos. Porque si la documentación de un software es parte integral del producto y se realiza en paralelo, ¿no resulta más coherente que los flujos de trabajo sean los mismos? Bajo este nuevo paradigma, escribir documentación no dista mucho de escribir código.

En síntesis, la metodología Docs like Code propone:
  • Abandonar el uso de gestores de contenido tradicionales en favor de herramientas colaborativas como GitHub (un repositorio de código muy popular entre los desarrolladores).
  • Adoptar lenguajes de marca ligeros (del inglés, lightweight markup languages) como formato, abandonando lenguajes complejos como XML. El ejemplo más conocido de estos lenguajes es Markdown.
  • Incorporar procesos de revisión continuos donde los revisores puedan registrar cambios en cualquier momento mediante los mecanismos de pull-request ofrecidos por GitHub.
  • Publicar regularmente la documentación del producto mediante el uso de generadores estáticos de páginas, que permiten transformar los textos en formato Markdown en código HTML.

GitHub

Millones de desarrolladores en todo el mundo usan GitHub como repositorio para el código de sus aplicaciones. Pero, ¿qué hace de GitHub un entorno tan atractivo para los aficionados, desarrolladores independientes y empresas? El éxito comercial de GitHub nace de su capacidad de simplificar el uso de la herramienta Git (una utilidad de software creada originalmente para gestionar el desarrollo de Linux) en una interfaz web fácil de usar. GitHub facilita además que múltiples personas pueden colaborar en un mismo proyecto de manera relativamente sencilla. La complejidad y diversidad del software actual convierten en imprescindible esta capacidad de la plataforma para escalar fácilmente.

Pero este cambio en los métodos de desarrollo de software no dista mucho de lo que ocurre en el ámbito de la documentación. Si en el pasado un manual era responsabilidad de un único redactor técnico hoy en día, con la creciente complejidad tecnológica y la integración continua de cambios, el resultado final precisa de la colaboración y coordinación de múltiples personas. El modelo de catedral impuesto por los gestores de contenido no ha sido capaz de dar respuesta a este cambio.

El momento es ahora

Lejos de ser solo un concepto, Docs like Code es también una realidad para empresas de software tan importantes como Microsoft, Amazon o Twitter. En Mayo de 2016 Jeff Sandquist (@jeffsand) anunciaba la nueva plataforma documental de Microsoft docs.microsoft.com con las siguientes palabras:

Toda la documentación está diseñada para permitir contribuciones de la comunidad. Cada artículo incorporar un botón de edición que te dirige al fichero fuente de Markdown en GitHub, donde puedes crear un pull request para reportar un error o mejorar el contenido.

Una buena parte de la documentación del fabricante reside ya en esta nueva plataforma documental, en una clara apuesta por el uso de sistemas abiertos. Otras empresas como Amazon han seguido esta tendencia y hoy es posible ver el botón Editar en GitHub en muchos de los artículos destinados a desarrolladores.


El especialista en documentación y redactor técnico Tom Johnson (@tomjohnson) escribía en un artículo del blog I’d Rather Be Writing, en un comentario dirigido a la raíz del problema del uso de gestores de contenido:

No más cajas negras para gestionar tu contenido. No más sistemas caros y propietarios que mantener. No más formatos-de-salida-imposibles-de-ajustar. Puedes integrarlo todo de manera simple, fácil y barata.

La enorme influencia que estas empresas tienen en el mundo del software propiciará, más tarde o más temprano, la adopción de modelos documentales abiertos tipo bazar en detrimento de modelos rígidos tipo catedral. Si el desarrollo más efectivo y ágil del software es el resultado de un proceso colaborativo de integración y publicación continua, el proyecto documental tiene necesariamente que adaptarse a esta nueva realidad.


]]>
Jorge Pérez Campo
tag:www.funcion1.com,2013:Post/1137923 2017-03-12T14:10:53Z 2017-03-12T16:45:00Z Por qué es difícil documentar errores

Documentar errores de software es una labor compleja. Los departamentos de soporte reclaman una gestión ágil y precisa de esta información que no siempre encaja bien con los flujos establecidos en otras tareas documentales. En este artículo expongo por qué los errores requieren un tratamiento diferenciado y propongo algunas ideas para mejorar su gestión documental.

El problema con los errores

El desarrollo de cualquier aplicación va necesariamente ligado a la aparición de errores. Cuando el número de posibles errores es pequeño -como ocurre, por ejemplo, con el software incorporado en muchos electrodomésticos modernos- su tratamiento se reduce a un breve apartado de resolución de problemas en la guía del usuario. En productos de software más complejos, la posibilidad de encontrar errores aumenta considerablemente. En su libro Code Complete, Steve McConnell, estima que la media de errores en la industria es de entre 15 y 50 errores por cada 1000 líneas de código. Cualquiera que sea la cifra final, puede llegar a ser muy alta si consideramos la extensión en líneas de código de muchos programas.

Tratar estos errores resulta complejo porque, como veremos más adelante, la naturaleza de este tipo de información es particular. Cuando el número de errores conocidos es pequeño, los redactores técnicos creamos una sección dedicada a la resolución de problemas en el propio manual del producto, o advertimos de la ocurrencia de problemas en forma de notas de texto. Pero el alcance de este planteamiento es limitado. Es, además, una solución que no contenta a nadie: los técnicos no tienen una forma directa de buscar esta información y los autores entendemos que funcionalidades y errores deben de ocupar sitios distintos en la documentación. Es por ello que muchos fabricantes de software diferencian entre funcionalidades y errores en su documentación. Vemos un ejemplo de ello en el área de soporte del fabricante Red Hat, donde estas dos áreas están claramente diferenciadas:

Otro ejemplo lo tenemos en la documentación de Microsoft, donde los contenidos de soporte (support) y funcionalidad de producto (library) son independientes:

Pero, ¿por qué resulta necesaria esta división?

Funcionalidades y errores

Hay 2 razones fundamentales que explican la separación entre la documentación de funcionalidades de producto y errores.

1. El origen y tratamiento de la información es distinto

Cuando describimos el funcionamiento de un software, los redactores técnicos lo hacemos en colaboración con el especialista (habitualmente un desarrollador o analista). La información facilitada por esta figura, junto con la documentación interna del producto (casos de uso, especificaciones de producto, wireframes, etc.) son la materia prima del artículo técnico. Nuestra función como redactores es destilar toda esta información y trasladarla a la documentación del producto de una manera ordenada.

Sin embargo, en el tratamiento de errores, el origen de la información reside en la figura del especialista de soporte. Él es -después del cliente- el primero en detectar y evaluar la gravedad del problema, y es también el primero en registrar los detalles del error en la herramienta de gestión de casos (en síntesis, una base de datos con los errores de producto reportados). A diferencia de lo que sucede con la documentación del producto, esta información no se encuentra ordenada, y puede ser difícil de encontrar por otros especialistas que trabajan con la misma herramienta. Solo la información de algunos de estos errores llega a la documentación final del producto como boletines de seguridad o artículos de soporte.

2. Los tiempos de publicación son distintos

La documentación de funcionalidades sigue un proceso de desarrollo constante, pero que viene pautado por la publicación de cada nueva versión del producto. Por el contrario, los errores se producen de forma intermitente durante todo el ciclo de vida del software. La información de soporte, por su propia naturaleza, requiere de un tratamiento ágil que le permita llegar al mayor número de especialistas de soporte posible. Esta diferencia en los ritmos de publicación explica también por qué funcionalidades y errores ocupan lugares distintos en la documentación del producto.

La siguiente tabla resume las diferencias entre uno y otro tipo de información:

Tratamiento de errores

Considerando estas diferencias ¿cómo podemos mejorar la gestión de errores en documentación? Propongo aquí dos ideas básicas.

1. Vincular el tratamiento de errores y funcionalidades

Salvo excepciones, son pocos los errores reportados que llegan a la documentación de usuario. En algunos casos, las herramientas de soporte no permiten extraer y analizar la información de una forma sencilla. En otros, no existen los flujos de trabajo para explotarla eficientemente. Este hecho resulta paradójico si pensamos en el valor que tiene esta información.

Sea cual sea la aplicación para la gestión de casos, debe permitir hacer búsquedas e, idealmente, puntuar (por ejemplo, a modo de like/dislike) el valor que cada caso tratado aporta para resolver un problema similar. El redactor técnico podrá así identificar los casos más consultados o mejor valorados internamente e incorporarlos a la documentación final del producto, que es ya accesible al usuario final. Los casos más críticos se publicarán como boletines de seguridad, mientras que los más populares se integrarán en área de soporte de la documentación (normalmente, en la base de datos de conocimiento o knowledge base).

Por último, la herramienta de gestión de casos usada por el especialista debe permitir realizar búsquedas en diferentes bases de datos y presentar un resultado unificado. Esto es esencial en grandes entornos, donde es común que cada área de soporte o país mantenga su propia solución.

La propuesta es, en definitiva, romper los silos de información y establecer flujos que permitan al redactor técnico descubrir los errores más comunes e incorporarlos, ya de una forma ordenada, a la documentación del producto.

2. Facilitar la creación de contenido de soporte

También se puede promover el desarrollo de nuevo contenido de soporte mediante plantillas de documento que el técnico pueda usar de forma sencilla. Elaborar estas plantillas no es complejo porque los artículos de soporte se ajustan a un patrón muy sencillo (normalmente Síntomas-Causa-Resolución). Los especialistas suelen agradecer estas iniciativas. Si el área de soporte puede generar la información en un formato predefinido, nuestra labor revisando, adaptando o traduciendo esa información será mucho más sencilla.

Desde hace varios años, Microsoft permite crear artículos en su Knowledge Base a cualquier especialista de soporte de la compañía. Este tipo de artículos, que pasan por un proceso de revisión interna antes de su publicación, abundan en la web del fabricante bajo el epígrafe de FAST PUBLISH (del inglés, publicación rápida):

Saber cómo tratar y gestionar la información de errores resulta más sencillo si entendemos las particularidades de esta información. Hemos visto que estas particularidades requieren de un tratamiento diferenciado pero no aislado. Bajo este escenario, los redactores técnicos debemos poner en marcha iniciativas que permitan mejorar el intercambio de información con el área de soporte.

]]>
Jorge Pérez Campo
tag:www.funcion1.com,2013:Post/1117699 2016-12-23T12:33:19Z 2016-12-26T19:25:05Z Forma y función del artículo técnico: el meta-artículo

En la última parte de esta serie de tres (ver entradas anteriores aquí y aquí) sobre el desarrollo del artículo técnico, se introduce el concepto de meta-artículo como elemento funcional básico de la información. El meta-artículo constituye la pieza de unión entre el artículo técnico (la forma) y la tarea del usuario (la función).

El manual de usuario “electrónico”

El paso del manual de usuario físico a la documentación web que hoy acompaña a muchos productos de software no ha estado libre de problemas. Con la popularización del ordenador personal, y años antes de la generalización de internet, los fabricantes de software comenzaron a sustituir las ediciones impresas de sus manuales por versiones electrónicas. Los ficheros de ayuda de Windows se generalizaron como la forma más efectiva y económica de hacer llegar al usuario la documentación de producto. Los primeros manuales electrónicos, con un contenido escasamente enlazado y motores de búsqueda limitados, se convertían muchas veces en una mera copia digital del manual en papel.


Estos manuales de ayuda electrónicos -a los que el comunicador técnico Mark Baker llamó acertadamente frankenbooks- incorporaban todas las limitaciones de un libro físico, pero sin aprovechar ninguna de las ventajas del nuevo medio electrónico. La tabla de contenidos -y no la búsqueda- continuaba siendo clave en el descubrimiento de información y cada entrada se fragmentaba frecuentemente en múltiples subentradas. El resultado era un manual de ayuda electrónico con tablas de contenido extensas, difíciles de manejar y donde abundaban apartados con poca información.

El salto final desde el manual electrónico hasta el manual web ha obligado a los redactores técnicos a replantear la manera de agrupar y enlazar el contenido. El cambio en los patrones de lectura y descubrimiento de la información que trajo consigo internet hacen que organizar la información en la web siguiendo el modelo de libro físico carezca de sentido. Si la tabla de contenidos había sido hasta entonces un elemento fundamental, las capacidades de búsqueda en la web junto con estos nuevos patrones de lectura (que discutimos ya en el primer artículo de esta serie) convertían a este elemento en secundario.

Escritura técnica orientada al artículo

Junto con la transformación del manual de ayuda físico en manual en formato web, uno de los avances más importantes en el desarrollo de documentación técnica ha sido el paso al modelo de documentación orientada a artículos. Si anteriormente el redactor técnico trataba al manual como un todo, la tendencia ahora es, claramente, organizar el contenido en torno a bloques discretos de información a los que llamamos artículos. La popularización de modelos de información como el propuesto por la especificación DITA han cimentado esta transformación.

A pesar de este avance, modelos como DITA siguen sin dar respuesta a cómo los artículos, entendiendo estos como bloques primarios de información, se relacionan entre sí de forma lógica para el lector. De hecho, en la teoría de la escritura orientada al artículo, la agrupación de artículos se desaconseja o se considera que va en detrimento de la capacidad de asimilar información por parte de lector (en una palabra, de su usabilidad). Tal como expone el comunicador técnico Tony Self en su artículo Desarrollo de información basada en artículo (originalmente en inglés, Topic-based Information Development):
Los cambios en los patrones de lectura y adquisición de información sugieren que los lectores ya no quieren leer en profundidad textos largos y lineales. En su lugar, la investigación sugiere que quieren leer de forma superficial, y leer sólo el mínimo que les permita realizar una tarea. Las estructuras de información basadas en artículos son más apropiadas para estos lectores impacientes.
Pero si, como definen estos modelos, cada artículo representa únicamente un tipo de información (tarea, referencia, concepto, etc.), ¿no corremos el riesgo de volver a aquellos manuales electrónicos del pasado, con múltiples entradas aisladas y difíciles de manejar? ¿No tendría más sentido agrupar funcionalmente aquellos artículos relacionados entre sí, incluso aunque pertenezcan a categorías distintas?

El hecho de que los patrones de lectura y adquisición de información hayan cambiado con la aparición de internet no está reñido con la creación de contenido de mayor longitud. Muy al contrario. De hecho, la extensión de un artículo, por sí sola, no debería ser un criterio válido para fragmentar el contenido. Muchas entradas de la Wikipedia incluyen artículos extensos, lo que como lectores no nos impide navegar por su contenido en busca de la información o dato necesarios. Sin duda, esta organización resulta mucho más útil que presentar la información en bloques discretos y discontinuos, obligando al lector a moverse de un nivel de contenido a otro, y rompiendo el patrón de lectura habitual.

Modelo A frente a modelo B

Los modelos de desarrollo de información basados en DITA, en un empeño por maximizar la capacidad de reutilizar el contenido (uno de los principales objetivos de la escritura orientada a artículos) son incapaces de dar respuesta al modo en que estos bloques se agrupan (tanto es así, que algunos autores no consideran DITA como un verdadero modelo de información).

El modelo A (ver imágen) ejemplifica el modelo propuesto por DITA. Bajo esta concepción, cada tipo de artículo se presenta como un elemento final y reutilizable de información. El modelo B, por el contrario, plantea que los distintos artículos se combinan en elementos de mayor entidad, a los que me he dado en llamar meta-artículos. Si el artículo supone el elemento constructor de la información, el meta-artículo constituye el elemento funcional.

El modelo A aconseja aislar las tareas de autoría de las de presentación. En palabras de Tony Self:
El formato y presentación son consideración posteriores a la autoría, y actividades posiblemente no realizadas por el autor técnico.
Pero, ¿es esto cierto? En mi opinión, este planteamiento ignora que la presentación del contenido (el cómo se relacionan entre sí los diferentes tipos de artículos) condiciona en gran medida el acceso a la información por parte del lector. El redactor puede y debe aislarse de elementos formales como el uso de fuentes, colores, espacios entre párrafos, etc., pero no puede ignorar la estructura final del artículo.

El decidir entre un modelo u otro dependerá de factores que, como redactores técnicos, deberemos sopesar para cada tipo de contenido y audiencia. Veamos dos casos para ilustrar esta idea. Pensemos por un momento en una aplicación ofimática como Microsoft Word. Las preguntas que un usuario de esta aplicación puede plantearse se resuelven normalmente con una breve explicación (añadir formato a una tabla, compartir un documento, insertar una ecuación, etc.). En estos casos, la información de contexto resulta innecesaria porque el objetivo del usuario es muy específico y el número de posibilidades muy reducido. Pero pensemos ahora en una caso más complejo, como puede ser la instalación y configuración de un servidor web. El técnico que se enfrenta a esta tarea requiere una información de contexto suficiente para entender aquello que va a llevar a cabo y evitar errores comunes. ¿Tiene sentido aquí separar la tarea en sí de la información de contexto? Separando ambas (por ejemplo, en dos artículos enlazados) perdemos la posibilidad no solo de atraer la atención del lector, sino también de facilitarle la información necesaria en el lugar donde se lleva a cabo su acción.

Usabilidad frente a reutilización

El problema se reduce, por tanto, a cómo presentar el contenido al usuario de una forma que sea coherente con su flujo de trabajo, y que a su vez permita reutilizar la información. DITA no cierra la posibilidad de agrupar diferente artículos, pero advierte contra los peligros de hacerlo, como podemos leer en la propia especificación de DITA 1.2:
Los artículos pueden definirse dentro de otros artículos. Sin embargo, la unión requiere un cuidado especial porque puede dar lugar a documentos complejos que son menos utilizables [en el sentido de usabilidad] y reutilizables.
Como enfatiza Mark Baker, el problema es que DITA prioriza la posibilidad de reutilizar un contenido sobre la usabilidad del mismo. El argumento de que la agrupación de los artículos hace el documento menos usable no parece sostenerse. De hecho, si nos fijamos, la usabilidad de un documento (en otras palabras, la capacidad de ese documento de aportar la información relevante para la tarea del usuario) es contraria en muchos casos a las posibilidades de reusar el contenido. Pensemos en las imágenes o los vídeos. Aunque la tendencia es ahora la de incorporar cada vez más elementos gráficos en la documentación técnica, durante mucho tiempo este contenido fue relegado por los costes de producción asociados y su escasa reutilización. Pero, ¿es este un contenido usable? ¿Da soporte a la tarea en cuestión que el usuario realiza? Claramente, la respuesta es sí. Usabilidad y capacidad de reutilización son, en muchos casos, elementos contrapuestos.

El meta-artículo da respuesta a la necesidad de desarrollar documentación que sea a la vez usable y reutilizable, y comienza a estandarizarse como la forma más adecuada de hacer llegar la información técnica al usuario, especialmente en tareas complejas como las que se llevan a cabo en los departamentos de IT.
]]>
Jorge Pérez Campo
tag:www.funcion1.com,2013:Post/1101364 2016-10-23T17:31:01Z 2016-10-23T17:33:43Z Céntrate (o cómo sobrevivir en un mundo de distracción)

Vivimos expuestos a un asalto constante de estímulos y notificaciones que, minuto a minuto, se apoderan de nuestra atención. Esta atención, necesaria para avanzar en nuestra carrera y en nuestra vida, se ha convertido en un bien escaso. Recuperar el terreno perdido no es una tarea fácil.

Respira


Observa tu respiración. Obsérvala por un instante. La mayoría de nosotros, al trabajar con la pantalla de nuestro ordenador o teléfono móvil, retenemos inconscientemente la respiración en un acto que la escritora Linda Stone bautizó como apnea del correo electrónico (originalmente, email apnea). Este hecho, aparentemente inocuo y que repetimos cientos de veces a lo largo del día, no pasa inadvertido para nuestro organismo. En su artículo Just Breathe: Building the case for Email Apnea (Solo respira: Argumentos acerca de la apnea del correo electrónico) publicado en Agosto del 2008, Stone describe en detalle algunas de las consecuencias que a largo plazo puede tener este comportamiento sobre nuestra salud. No resulta extraño que una de estas consecuencias sea el estrés y las enfermedades derivadas del mismo.


Dejando de lado el factor puramente biológico, la respiración juega un papel determinante en nuestra capacidad de atención y concentración. Las técnicas de mindfulness y meditación se basan en gran medida en un reaprendizaje y control consciente de la respiración. Estas prácticas, cada vez más populares y demandadas, llegan a la sociedad occidental como herramientas para conseguir una vida más centrada en cada momento y más plena. No son necesarias grandes dotes de observación para darse cuenta de cómo las actividades de nuestro día a día nos sitúan justamente en el extremo opuesto.

La meditación ha dejado ya de tener el estigma de práctica mística que se le atribuía hace solo unos años. Los cursos de meditación y mindfulness se han popularizado y cada vez es mayor el número de personas que incorporan estas herramientas con normalidad en su vida. La aceptación y difusión de estos recursos ha sido notable en estos últimos años, algo que solo se puede explicar como la respuesta de nuestra sociedad a una creciente ansiedad y dispersión de nuestra atención.


Una respiración controlada y consciente, como la que se realiza durante la meditación, mejora nuestra capacidad de atención y fija el marco para un desarrollo cognitivo sano, como puede concluirse de los resultados de diferentes estudios y meta-estudios. En palabras de la propia Stone, “en el corazón de la atención deliberada se encuentra la respiración deliberada. Respiración, atención y emoción, son conmutativas”.

Atención y productividad

En una sociedad donde las interrupciones son casi constantes, la atención se ha convertido en un recurso escaso. Como explica el filósofo Byung-Chul Han en La sociedad del cansancio (Edit. Herder, 2016), el exceso de estímulos, informaciones e impulsos “modifica radicalmente la estructura y economía de la atención”, y nos reduce a máquinas capaces de reaccionar a cualquier estímulo pero incapaces de reflexionar sobre sus propias acciones. Han señala además lo contradictorio de que esta fragmentación de nuestra capacidad de concentración se produzca precisamente en una época en la que “el aumento de la carga de trabajo requiere una particular técnica de administración del tiempo y la atención”.

Solo necesitamos echar un vistazo a nuestro alrededor para darnos cuenta de esta realidad. Contestamos a los correos electrónicos en el tren y el metro, interrumpimos cualquier tarea para revisar la última notificación de nuestros teléfonos móviles y pasamos frenéticamente de una reunión a otra -revisando más notificaciones por el camino- sin apenas tiempo para sacar conclusiones de aquello que hemos discutido. Este estado, que Han describe como “pura agitación que no genera nada nuevo, [solo] reproduce y acelera lo ya existente” es aceptado hoy como símbolo de productividad. Asumimos que todo aquello que nos mantiene alerta y ocupados nos hace productivos, sin pararnos a pensar en cómo repercute toda esta actividad en nuestras vidas, y llegamos al absurdo de afirmar que la ansiedad y el estrés son beneficiosos porque nos mantiene alerta y nos hace máquinas de trabajar más eficaces.


En esta situación, no resulta extraño que aquellas tareas que requieren un esfuerzo mental ininterrumpido y durante varias horas queden relegadas siempre a un segundo lugar, justo porque en ese estado de agitación solo podemos reaccionar a la crisis del momento, al último correo electrónico o a la última notificación. Nos hemos acostumbrado a ver como un hecho normal perder dos terceras partes de nuestra jornada laboral en la bandeja de entrada. Ponemos todo el énfasis en tareas puramente mecánicas como reuniones, trabajo administrativo o almacenar y compartir información, convirtiéndonos así en el animal laborans -eficiente pero irreflexivo- que la filósofa Hannah Arendt describe en La condición humana (Edit. Paidós, 1993). La actual cultura del trabajo promueve y ejemplariza esta falsa productividad provocando que para muchas personas esta actividad febril sea la única forma de demostrar su valor en la empresa. La dispersión y la multitarea son ahora la norma, pero ¿a qué coste? El estrés es solo uno de los subproductos que trae consigo la sociedad del animal laborans. La desilusión, la insatisfacción, el miedo al fracaso y en último término, la depresión, son también consecuencias naturales.

Hemos dejado de lado la reflexión necesaria para el desarrollo de nuestras capacidades y el verdadero progreso en nuestra vida y nuestra profesión. Mindfulness significa conciencia plena, y supone un estado mental en el que nuestra voluntad está dedicada enteramente a una actividad y no se ve interrumpida por ninguna otra cosa. Y es solo en este estado de atención donde la productividad bien entendida se manifiesta.

Trabajo profundo

Para el profesor Carl Newport, autor de varios libros sobre técnicas de estudio y productividad personal, el salto de una actividad profesional mediocre a una sobresaliente solo puede venir dado por la dedicación consciente y focalizada de nuestro tiempo. Esta dedicación, a la que el autor llama trabajo profundo (originalmente en inglés, deep work) require una gran fuerza de voluntad y un elevado esfuerzo. El trabajo profundo no es divertido, pero es la única forma de obtener avances verdaderos en aquello a lo que nos dedicamos. Como explica el propio autor en su libro Deep Work (Piatkus Pub., 2016), “si no has dominado esta habilidad fundamental [del trabajo profundo] tendrás dificultades para aprender cosas complejas o producir a un nivel superior” (2016, p.32) .Las afirmaciones de Newport nos llevan inevitablemente a un reflexión y un replanteamiento de nuestra forma actual de trabajar o estudiar.

Esta reflexión está en consonancia con lo apuntado por Geoff Colvin en Talent is overrated (El talento está sobrevalorado. Portfolio-Penguin Pub., 2008). En el estudio The role of deliberate practice in the acquisition of expert performance (El papel de la práctica deliberada en la adquisición de un rendimiento de élite. KA Ericsson, RT Krampe, C Tesch-Römer. Psychological review 100 (3), 363) llevado a cabo con varios violinistas de un prestigioso conservatorio alemán y ampliamente comentado por Colvin en su libro, se pone de relieve que el factor decisivo para diferenciar a los buenos violinistas de los mejores no es tanto las horas de práctica como las horas de lo que los autores del estudio llaman práctica deliberada. Se entendiende por deliberada aquella práctica repetida en el tiempo, que supone un elevado esfuerzo intelectual y que requiere de toda nuestra capacidad de atención. En definitiva, alcanzar las metas deseadas en cualquier actividad no pasa solo por dedicar más tiempo a esa actividad sino también por dedicar un tiempo de mayor calidad. Se rompe así con la afirmación -basada precisamente en el mismo estudio de Ericsson, Krampe y Tesch-Römer- del escritor Malcolm Gladwell en Fuera de serie (Ed. Taurus, 2009 y publicado originalmente en inglés como Outliers), donde se afirma que para sobresalir en una actividad son necesarias al menos 10.000 horas de dedicación. La excelencia en cualquier campo no está determinada tanto por la cantidad, como por la calidad de nuestro tiempo.

Lo cierto es que existe una relación entre la atención, la calidad del tiempo de trabajo y nuestra motivación. Poner toda nuestra atención en aquellas actividades que consideramos importantes en nuestra vida o en nuestra profesión se traduce en un tiempo de mayor calidad (trabajo profundo). Este tiempo es precisamente el que nos permite progresar cualitativamente en estas actividades y a su vez nos motiva para seguir realizándolas. Como apunta Newport, conseguir la concentración necesaria para un tiempo de calidad  nunca ha sido sencillo, pero las empresas de medios y redes sociales han hecho nuestra labor mucho más difícil. El bombardeo constante de noticias y notificaciones resulta demasiado atractivo y el temor a “perderse algo” demasiado angustioso. Saber reconocer estas situaciones y actuar contra ellas es fundamental.

Consejos para una vida más centrada

Internet y las mejoras en inteligencia artificial y robótica han hecho obsoletos muchos tipos de trabajo tradicional. Pero la realidad es que una gran mayoría de los trabajos que realizamos hoy en día no pueden ser reemplazados por máquinas o por un software. Y no pueden serlo fundamentalmente porque el valor que aportamos como individuos se realiza en un nivel cognitivo que no puede ser programado en un software. En un mundo laboral contradictorio, donde las empresas buscan la uniformidad del individuo a la vez que reclaman innovación, el trabajo deliberado y profundo en nuestra actividad profesional puede convertirse en el factor diferenciador. Este trabajo no es divertido, pero como apunta Colvin “tiene que ser así. Si las actividades que llevan a la excelencia fueran fáciles y divertidas entonces todo el mundo las haría y no se distinguiría a los mejores del resto”. Pero, ¿qué estrategias podemos poner en marcha que nos permitan avanzar verdaderamente en nuestra profesión?

Organiza tu tiempo

Enfocar nuestra vida en aquello que de verdad importa y evitar las distracciones requiere una planificación. Diariamente debemos luchar contra todas aquellas cosas que reclaman nuestra atención: redes sociales, notificaciones, televisión, videojuegos, etc. Nuestra mejor arma en esta lucha es nuestra voluntad y nuestro calendario. Si de forma rutinaria bloqueamos horas en nuestra agenda para reunirnos con otras personas, ¿por qué no bloquear tiempo para reunirnos con nosotros mismos? Si necesitas tiempo para pensar en esa importante presentación, en ese nuevo plan de márketing o en la solución para el problema que lleva meses persiguiéndote, bloquea el tiempo necesario en tu calendario para estas tareas. Bloquea ese tiempo y comprométete a cumplirlo de la misma forma que lo harías en una reunión con otra persona.

Una objeción común para no llevar a cabo esta práctica es que las actividades del día a día no permiten bloquear el periodo de tiempo enfocado e ininterrumpido necesario. Resulta paradójico, sin embargo, que en esa escasez de tiempo, sí hemos sabido encontrar el hueco para dedicar varias horas a las pantallas de nuestro teléfono móvil o televisor en una distracción que mucha veces resulta vacía.

Reduce la ingesta de información

En su libro The information diet (La dieta informativa. O'Reilly Media, 2012), Clay A. Johnson compara la información que recibimos y consumimos actualmente con la comida basura. Esta información no está hecha para hacernos conscientes de la realidad del mundo a nuestro alrededor sino que, de forma análoga a la hamburguesa de las cadenas de comida rápida, es fabricada por los grandes medios de comunicación para ser de apetitosa, de rápido consumo y -sobre todo- adictiva.



El consumo constante de información convenientemente procesada no solo distorsiona nuestra capacidad de concentración, también reduce nuestra tolerancia a medios que requieren un mayor esfuerzo intelectual. El propio Johnson relata así este hecho en su libro: “hace algunos años, me encontré completamente incapaz de leer más allá de mil palabras. No había manera de que pudiera leer un artículo extenso o un libro. El concepto de leer de un libro, mucho menos escribir uno, era completamente ajeno a mí”.

Optar por una dieta informativa supone, ante todo, cambiar la relación que mantenemos con nuestro teléfono móvil. Acciones tan sencillas como eliminar aplicaciones, borrar nuestra presencia en redes sociales, o sustituir algunas horas de televisión y YouTube por un libro favorecen nuestra capacidad de atención a largo plazo y disminuyen progresivamente nuestra dependencia del teléfono móvil. Especialmente en lo referente a redes sociales, resulta inquietante cómo en apenas unos pocos años estos servicios se han adueñado por completo de nuestros días. Pensemos por un momento si la forma en la que empleamos nuestro tiempo es la que queremos y la que nos hace sentir bien.

Medita

Afortunadamente, practicar la meditación ya no es visto como algo esotérico y está cada vez más normalizado. La meditación proporciona, entre otros muchos beneficios que están ampliamente documentados, un aprendizaje de técnicas respiratorias y una mejora de la capacidad de concentración que son claves para la ejecución del trabajo profundo.

Aprender a meditar es, además, sencillo y no requiere de ningún equipo, instalación o material especial aparte de nuestra voluntad para llevarlo a cabo. Aunque existen muchas aplicaciones para iniciarse en el mundo de la meditación y el mindfulness, mi recomendación es no utilizar estas aplicaciones como punto de partida. Existen multitud de centros que imparten cursos y organizan monográficos sobre estas técnicas donde encontraremos un asesoramiento adecuado. Iniciarnos en estas prácticas con otras personas nos permitirá también compartir experiencias y ver con mayor normalidad estas actividades.

Practica el trabajo profundo

El trabajo administrativo al que nos enfrentamos hoy en día no parece tener fin. Podríamos estar trabajando durante días sin agotar todas las tareas administrativas que se nos demandan. Pero es justamente este trabajo administrativo el que nos impide desarrollarnos en nuestra profesión. Como apunta Newport, la única escapatoria que tenemos los trabajadores es la de ser conscientemente irresponsables: decir no a ciertas reuniones, no a ciertas actividades y no a ciertos correos electrónicos. En definitiva, convertir el trabajo profundo en la prioridad y no en algo que nunca llegamos a realizar por falta de tiempo.

Bloquea periodos de tiempo ininterrumpidos de 2-3 horas en la tu agenda para pensar y profundizar en aquellos temas que resultan importantes en tu profesión -o en tu vida. Comprométete a emplear este tiempo enteramente en la actividad en cuestión, dejando de lado cualquier posible distracción. Y si la cultura de la empresa o el puesto de trabajo no nos permite realizar las acciones que nos hacen avanzar profesionalmente, es quizás el momento de plantearse si estamos en el mejor sitio para desarrollar nuestra carrera.

]]>
Jorge Pérez Campo
tag:www.funcion1.com,2013:Post/1095157 2016-10-02T05:23:03Z 2016-10-03T18:54:02Z 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).
]]>
Jorge Pérez Campo
tag:www.funcion1.com,2013:Post/1091195 2016-09-18T16:33:05Z 2016-09-19T10:48:28Z 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.
]]>
Jorge Pérez Campo
tag:www.funcion1.com,2013:Post/1088575 2016-09-10T16:11:22Z 2016-09-12T21:57:03Z 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.

]]>
Jorge Pérez Campo
tag:www.funcion1.com,2013:Post/1084544 2016-08-31T12:05:00Z 2016-09-01T14:00:05Z 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)
]]>
Jorge Pérez Campo
tag:www.funcion1.com,2013:Post/1081168 2016-08-14T21:34:36Z 2016-08-15T06:25:52Z 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.


]]>
Jorge Pérez Campo
tag:www.funcion1.com,2013:Post/1075375 2016-07-25T12:03:15Z 2016-07-25T12:03:15Z 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)
]]>
Jorge Pérez Campo
tag:www.funcion1.com,2013:Post/1069260 2016-07-03T12:30:04Z 2016-07-04T20:59:33Z 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.

]]>
Jorge Pérez Campo
tag:www.funcion1.com,2013:Post/1054041 2016-06-16T09:33:00Z 2016-06-16T09:34:45Z 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.

]]>
Jorge Pérez Campo
tag:www.funcion1.com,2013:Post/1059416 2016-06-03T17:55:12Z 2016-06-03T18:10:19Z ¿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)
]]>
Jorge Pérez Campo
tag:www.funcion1.com,2013:Post/1051351 2016-05-18T09:28:04Z 2016-06-16T09:33:38Z 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.

]]>
Jorge Pérez Campo
tag:www.funcion1.com,2013:Post/1048405 2016-05-13T08:40:55Z 2016-05-13T08:40:55Z Microsoft marca el camino a seguir en documentación técnica

El nuevo servicio documental de Microsoft es mucho más que un cambio estético en la plataforma de contenidos.

La pasada semana, Microsoft dio a conocer su nueva plataforma documental docs.microsoft.com. Este cambio, detallado en la primera entrada del blog del equipo, incluye elementos que no resultan novedosos en sí mismos, pero que sí lo son cuando se trasladan al ámbito de la documentación técnica. El aspecto de la documentación es ahora más parecido al de un blog que al del clásico documento técnico, con artículos más cortos y la incorporación de elementos como el tiempo de lectura de cada artículo, tipografías de mayor tamaño y diversas herramientas de comentario que recuerdan instantáneamente a Medium.


Las nuevas opciones de comentario y petición de cambios se añaden al clásico cuadro de sugerencias al final de cada artículo (que se mantiene). Con todas estas opciones y la posibilidad de añadir notas a cada párrafo no queda claro, sin embargo, qué respuesta pueden esperar los usuarios y cómo se integrarán las sugerencias enviadas en el documento final.

Pero la novedad más relevante no es estética. La gestión de cambios se realiza ahora desde GitHub, lo que permite solicitar revisiones del documento fuente mediante peticiones pull en la plataforma. Y todo ello aprovechando la sencillez de Markdown, lenguaje cuyo uso se está popularizando en los últimos años. Este uso de la plataforma GitHub no es nuevo -de hecho, Microsoft lo utilizaba ya en otras partes de su documentación-, pero por su generalización y la importancia de Microsoft, marca un punto de inflexión y un camino a seguir por otros fabricantes.

Jeff Sandquist, autor del artículo, señala también que los cambios incorporados no son sólo estéticos o de funcionalidad, sino también de contenido. Aunque no es mucho más lo que se dice sobre este aspecto, el comentario parece indicar que la documentación estará más orientada a la realización de tareas, algo que se puede ver ya en los artículos técnicos de Azure.

Aquellos que, de una u otra forma, trabajamos con la documentación del fabricante, hemos visto cómo se sucedían pequeños cambios en los últimos años, pero sin ninguna transformación significativa. Microsoft acomete así una transición necesaria, después de un tiempo en los que sus tres grandes áreas documentales -TechNet, MSDN y más recientemente, Azure- parecían evolucionar por caminos distintos.

El contenido de la nueva plataforma es aún escaso, pero los cambios introducidos apuntan a una documentación más adaptada a las necesidades del usuario, mejor estructurada y posiblemente con menos errores, gracias a las nuevas herramientas de comentario.


(este artículo fue publicado originalmente en LinkedIn el 11-05-2016)
]]>
Jorge Pérez Campo
tag:www.funcion1.com,2013:Post/1044320 2016-04-30T21:52:23Z 2016-05-01T12:23:46Z 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.
]]>
Jorge Pérez Campo
tag:www.funcion1.com,2013:Post/1027811 2016-04-07T21:49:34Z 2016-05-03T13:10:49Z Consejos para mejorar tu documentación técnica

La documentación es una herramienta fundamental en el día a día los departamentos de IT. Elaborar guías adaptadas a las necesidades concretas de cada equipo es clave a la hora de compartir información y experiencia. Una características común a estos documentos de uso interno son las diferencias en el estilo y el formato con el que se presenta la información. Este artículo muestra consejos sencillos para mejorar esta documentación.

Una buena parte de las guías de referencia que se generan en los departamentos de IT encuentran en formato Word o PDF. Word sigue siendo el programa de edición más común dentro y fuera del mundo de la empresa. Pero resulta llamativo que, a pesar de las opciones incorporadas a este software a lo largo de los años, la forma en la que lo usamos hoy no es muy distinta de la de hace 20 años. Parece razonable preguntarse, ¿es esta la mejor opción?

Antes de aventurarnos en la redacción del documento, pensemos por un momento en la mejor forma de hacer llegar el contenido a nuestra audiencia. Si tenemos en cuenta que las guías técnicas elaboradas por equipos de IT son normalmente de uso interno, parece tener sentido trabajar en algún medio web al que los usuarios puedan acceder fácilmente y en el que sea posible realizar comentarios de forma sencilla, como una wiki o el propio Google Docs. Estos medios permiten incorporar el ciclo de revisión dentro del propio ciclo de vida del documento, es decir, no hay un tiempo delimitado para revisar el documento o publicar una nueva versión ya que el contenido está siempre actualizado y siempre disponible para su revisión.

He extraído este listado de recomendaciones basándome en un documento interno que se me pidió revisar. Casi todos los ejemplos utilizados están tomados de la documentación técnica de Microsoft en MSDN.

Escribe con un lenguaje sencillo y directo

Al escribir un documento técnico debemos acercarnos al punto de vista del lector, utilizando siempre un tono directo y empático. El uso de palabras y expresiones sencillas debe ir acompañado del uso del término adecuados en todo el texto. Cuando empleamos términos distintos para referirnos a una misma cosa, el lector no familiarizado con la materia puede asumir que en realidad estamos hablando de cosas distintas. Evitemos también usar jerga o acrónimos que no son de uso común.

Usa la voz activa siempre que sea posible

Adoptar la voz activa nos acerca al usuario del documento y simplifica la comprensión del texto. En este caso es el usuario -o el objeto de la acción- y no la acción, quien adopta el papel activo. Veamos dos ejemplos de uso de la voz pasiva y su correspondiente cambio a voz activa:

Voz pasiva:

The backup process can be canceled at any time. / El proceso de copia de seguridad puede ser cancelado en cualquier momento.

The encryption mechanism is provided by the background secproc.d daemon. / El mecanismo de encriptación es realizado en segundo plano por el demonio secproc.d.

Voz activa:

You can cancel the backup process at any time. / Puedes cancelar el proceso de copia de seguridad en cualquier momento.

The secproc.d background daemon provides the encryption mechanism. / El demonio  secproc.d realiza en segundo plano el mecanismo de encriptación.

Utiliza la forma presente del verbo

Usar de la forma presente del verbo facilita la comprensión del texto y proporciona al lector seguridad sobre sus acciones. Veamos un ejemplo usando la forma futura:

To continue, click Install. SQL Server Setup will first install the required prerequisites. / Para continuar, haz clic en Instalar. El Instalador de SQL Server instalará primero los prerrequisitos necesarios.

y el mismo ejemplo con la forma presente:

To continue, click Install. SQL Server Setup installs the required prerequisites first. / Para continuar, haz clic en Instalar. El Instalador de SQL Server instala primero los prerrequisitos necesarios.

Elimina las palabras innecesarias

Como ya he comentado, una de nuestras prioridades es acercar el documento al lector, mediante un lenguaje sencillo y evitando construcciones complejas. Por ejemplo, la siguiente expresión:

In order to complete the backup process select Finish. / Con el fin de completar el proceso de copia de seguridad, selecciona Finalizar.

la podemos simplificar fácilmente:

To complete the backup process, select Finish. / Para completar el proceso de copia de seguridad, selecciona Finalizar.

Otro ejemplo es el uso de palabras innecesarias como recommended (recomendado) o please (por favor):

It is recommended to use a high-performance drive for the database journal. / Es recomendable usar un disco de alto rendimiento para el journal de la base de datos.

Como autores del documento, se da por sentado que lo allí escrito es nuestra recomendación. Podemos simplificar esta expresión diciendo:

Use a high-performance drive for the database journal. / Utiliza un disco de alto rendimiento para el journal de la base de datos.

En el caso de please, se emplea generalmente para rebajar -digámoslo así- el carácter imperativo del uso de la voz activa. Siempre que el tono y voz general del documento sea sencillo y directo, no debemos preocuparnos por esta cuestión.

Usa las imágenes de forma correcta

Una de las razones por las que el uso de las imágenes es escaso en la documentación técnica profesional es que su gestión es compleja. Si además estas imágenes tienen que mostrarse en diferentes idiomas, el problema se multiplica. Antes de incluir una nueva imagen, debemos plantearnos si hacerlo aporta valor a aquello que queremos describir. Estas son algunas pautas al tratar imágenes:

Incorpora imágenes para aclarar el funcionamiento de interfaces

Esta situación se da en interfaces de usuario pobremente diseñadas, donde el flujo de acciones que ha de seguir el usuario para completar la tarea no está claro. En estos casos conviene añadir imágenes resaltando los elementos de la interfaz necesarios para completar la tarea. Una imagen bien empleada puede simplificar enormemente el flujo de trabajo del lector.

Añade un borde estándar para las capturas de pantalla

Cuando tengamos que pegar capturas de pantalla en un texto, es conveniente añadir un borde a la imagen. De esta forma evitamos el fondo de la imagen se confunda con el fondo del documento, provocando una separación desigual de los elementos en pantalla:

Ajusta el tamaño de la imagen a la acción que estamos describiendo

Debemos evitar usar capturas de pantalla que incluyen un area demasiado grande o demasiado pequeña. Si el paso que estamos redactando describe un cuadro de diálogo concreto en la interfaz de usuario, carece de sentido incluir una captura de pantalla de todo el escritorio.

Divide tareas complejas en subtareas

Las tareas con un gran número de pasos son más difíciles de seguir y entender. Pensemos que si el lector ha de fijar su atención en una tarea que tiene 32 pasos, es fácil que pierda la atención en algún momento, con el riesgo añadido de dejar atrás algún paso esencial dentro del proceso. No siempre es posible describir una tarea con un número reducido de pasos, pero siempre podemos dividirla en subtareas.

Usa listas y flujos para resumir procesos complejos

La instalación y configuración de ciertos paquetes de software puede llegar a ser enormemente compleja. Normalmente esto sucede cuando el flujo de acciones no es único, o cuando se llevan a cabo varias acciones en paralelo. En todos estos casos es casi imprescindible acompañar el texto con un diagrama de flujo (workflow) que permita entender la tarea en su conjunto. Estos diagramas no son fáciles de realizar, pero el tiempo invertido en ellos aporta un gran valor al documento.

En otros casos, el lector está muy familiarizado con en el proceso que se va a realizar, pero necesita una guía de referencia rápida. Es lo que comúnmente llamamos una lista de comprobación o checklist. Al trabajar con estas listas, lo más común es añadirlas o enlazarlas al final del documento como un anexo.

Describe una acción completa en cada paso

Cada paso en un proceso define una acción completa del usuario. Veamos un ejemplo:

4. In the right pane of the Database Engine Tuning Advisor GUI, type MySession in Session name.

5. Select File for your Workload, and click the Browse for a workload file button to locate the MyScript.sql file that you saved in Step 1.

El paso 5 en esta tarea incluye varias acciones (select, click, locate) pero todas ellas forman parte de una misma acción completa (cargar un fichero en el programa).

Si es necesario realizar alguna aclaración sobre una acción, es mejor hacerlo dentro del paso correspondiente de la tarea, y no como un nuevo paso. El siguiente ejemplo ilustra la forma correcta de añadir esta información:

10. On the Feature Selection page, select the components for your installation.

SQL Server Setup will install the prerequisite that are not already installed during the installation step described later in this procedure.

11. On the Server Configuration — Service Accounts page, specify login accounts for SQL Server services.

En el siguiente ejemplo el uso no sería correcto, ya que el paso 2 no es realmente un paso en la tarea, sino una aclaración sobre el paso anterior:

1. Click the import configuration button.
2. The Configuration import dialog appears.

3. Wait until the end of the process.

Establece un formato único para elementos comunes

Usar un estilo unificado para los elementos de la interfaz mejora el aspecto visual del documento y facilita su lectura. Habitualmente queremos destacar tres elementos al describir un proceso:

  • Nombres de ficheros o carpetas.
  • Elementos de la interfaz de usuario (botones, menús, etc.).
  • Ejecución de sentencias o comandos.

Debemos definir un único estilo para esto tres elementos y ser constantes en su uso a lo largo del documento. Este sería un ejemplo que podemos tomar como punto de partida:

Elemento: Nombres de ficheros o carpetas
Estilo: Letra cursiva. Ejemplo: Double click the setup.exe file.

Elemento: Componentes de la interfaz de usuario.
Estilo: Letra negrita. Ejemplo: Click Run and then click OK.

Elemento: Código, sentencias o comandos.
Estilo: Letra de ancho fijo. Ejemplo: Type <setup.exe /a> to start the setup process

A pesar de la extensión y profundidad común a todas las guías de estilo, la mejora más inmediata y apreciable se consigue con la aplicación de un conjunto de normas sencillas. Recordar y practicar estas normas no es complejo, y el beneficio a corto y largo plazo será considerable.

]]>
Jorge Pérez Campo