Cómo escribir una guía visual para el usuario final para su software

“Escribir es fácil. Todo lo que tienes que hacer es tachar las palabras equivocadas «. – Mark Twain

No se me escapa la ironía de que esta es una guía de texto de formato largo sobre cómo escribir guías visuales para el usuario final. Inicialmente consideré ofrecer esto como un documento visual en lugar de una publicación de blog, pero la verdad es que algunas ideas se comunican mejor a través de texto.

He visto demasiada documentación de usuario final incorrecta a lo largo de los años y he corregido muchas guías de usuario final para software escrito para usuarios internos.

He escuchado quejas de usuarios de que el software o la solución en cuestión no es fácil de usar. Si bien esta publicación no trata sobre un buen diseño de UI / UX, muchas veces los escritores técnicos que escriben la guía del usuario final contribuyen a la tensión del usuario final.

Es posible que estos escritores técnicos no sean los que desarrollaron el software, por lo que es probable que no participen en el diseño de UI / UX. Aún así, pueden aliviar parte de la carga de los usuarios finales escribiendo guías visuales decentes.

En los últimos años, ha habido una proliferación de software y herramientas detrás de los firewalls corporativos, y algunas de las guías que he visto son bastante vergonzosas. Algunas «gemas» que he visto a lo largo de los años incluyen:

• Haga clic donde dice «Haga clic aquí»
• Espere mientras la pantalla termina de cargarse
• «Cómo encontrar este documento» (si lo estoy leyendo, ¿no lo he encontrado ya?)
• No haga clic en «Cancelar»

En esta publicación, le mostraré cómo escribir una guía visual para el usuario final que sea fácil de leer y use imágenes y diagramas para guiar al usuario sobre cómo usar su software, sección por sección. Entiendo que a los desarrolladores de software no les gusta escribir sin código. Sin embargo, si desea que le guste su software, escribir una buena guía para el usuario final es una habilidad esencial, incluso si todo lo que hace es ayudar al redactor técnico.

Antes de comenzar, permítanme enfatizar que Una buena redacción técnica no se trata de hacer que las personas lean su documento, sino de omitirlo.. No quiere que nadie tenga que leer ninguna parte de su documento que no sea absolutamente necesario, así que tenga en cuenta este principio básico al escribir sus guías y el resto de esta publicación tendrá mucho más sentido.

Escribir la página de título

El primer elemento visual de su guía es su página de título. Aquí es donde debe comenzar su proceso de eliminación. Su primer proceso de eliminación es eliminar a las personas que no necesitan leer el documento y atraer a las que sí lo hacen.

Debido a esto, debe incluir una fecha de publicación en su página de título. Esto ayudará al lector a determinar si la publicación es demasiado antigua o demasiado nueva para el área de software que está tratando de estudiar.

El usuario debe poder leer el título y la fecha de publicación y determinar si desea o no leer el documento.

Recuerde, su documento se enviará por correo electrónico, se publicará en la intranet corporativa y se vinculará desde el software.

Por esa razón, incluya un logotipo de su software para que actúe como un marcador visual para cualquier persona que pueda estar interesada en el documento. También incluya un título descriptivo para que si alguien lo lea, pueda determinar si debe leer más.

Algunos títulos de muestra incorrectos incluyen:

• Guía del usuario final (¿guía del usuario final sobre qué software?)
• Como guiar
• Notas de la versión del usuario

Los buenos títulos incluyen:

• Guía del usuario final para el Departamento Legal (Cómo realizar revisiones de memorandos legales)
• Cómo realizar revisiones legales de memorandos en el sistema de revisión de documentos legales
• Guía del usuario para realizar revisiones legales de memorandos de clientes en el sistema de revisión de documentos

Observe que cada título le dice al usuario que no necesita leer esto si no está en el departamento legal. No es necesario que lea esto si no está realizando una revisión legal y si no está involucrado en la revisión legal de los memorandos de los clientes, esta guía no le resultará útil.

¿Recuerdas el proceso de eliminación? Debería deshacerse de los usuarios desinteresados ​​directamente desde la página de título.

Tabla de contenido

Prefiero escribir la tabla de contenido (TOC) antes de escribir el resto del documento. La mayoría de los procesadores de texto modernos crean una tabla de contenido para usted, pero escribir una usted mismo con anticipación tiene múltiples beneficios. Le brinda una hoja de ruta de lo que debe escribir y le ayuda a organizar sus pensamientos.

La tabla de contenido también es el segundo elemento visual de su guía. Sé que se compone principalmente de texto, pero el texto, la sangría, la agrupación y la fuente son importantes en términos de estética.

Al escribir una buena tabla de contenido, las historias del software en cuestión deberían ser su guía.

Escriba cada sección como empezaría una historia de usuario.

Tome esta declaración de apertura, por ejemplo, «Como abogado, me gustaría …»

Esto le dice al usuario que si no es un abogado, debe saltarse esa sección, ya que tendrá poco o ningún beneficio para él.

Además, el orden de las secciones es importante. Debes escribir las historias en el orden del número de usuarios. Por ejemplo, si hay más abogados que utilizarán el software, primero debe escribir la sección de abogados, luego las poblaciones de usuarios más importantes, y así sucesivamente.

Para cada subsección, escriba la oración como lo haría en una historia similar a lo que le gustaría lograr al usuario.

Dado que su sección comenzó con «Como abogado, me gustaría …», cada subsección debe referirse a lo que le gustaría hacer al abogado, como «revisar un documento en mi cola» o «devolver un documento en mi cola a la oficina administrador para más ediciones ”, etc.

Nuevamente, cada subsección debe estar en el orden en que es más probable que el usuario realice las tareas. Si es más probable que un abogado realice la tarea A, debería ser primero, y luego la tarea B, y así sucesivamente.

La tabla de contenido debe limitarse a dos páginas. Si tiene más de dos páginas de contenido, tal vez debería considerar dividir la guía. Por ejemplo, tres guías independientes para tres personas / usuarios distintos. De esta manera, aún puede discutir todos los aspectos de su software de una manera fácil de seguir.

Si está familiarizado con Agile, estará familiarizado con historias de usuarios y epopeyas. Utilice las personas que desarrolló en sus historias y los objetivos que a cada persona le gustaría lograr como guía para escribir los encabezados de las secciones.

Utilice el proceso de eliminación. Use los zapatos de los usuarios. Leer su guía no es su trabajo; solo necesitan realizar una tarea y volver a su trabajo habitual, por lo que debería ser fácil para ellos encontrar lo que necesitan.

Las señales visuales que debe proporcionar en su TOC son:

• Agrupación clara de tareas que debe realizar una sola persona
• Separación de personas por sección
• Jerarquía clara de las tareas (las más frecuentes primero)

Una tabla de figuras (TOF) es otro elemento visual importante, y sí, es una representación visual de elementos visuales.

No todas las capturas de pantalla de su documento merecen una cita en la tabla de figuras. Incluya solo aquellas capturas de pantalla en el TOF que sean de particular importancia. Quizás un flujo de proceso o un esquema de una pieza.

Sección

Cada sección y subsección debe escribirse como: «Como persona, me gustaría lograr mi objetivo».

Como cada subsección debe titularse con el objetivo que la persona le gustaría lograr, escriba cada subsección con los pasos que el usuario debe seguir para lograr ese objetivo.

Nunca asuma que un usuario sabe algo o ha hecho algo hasta ese momento. Suponga que el usuario nunca ha utilizado el sistema y suponga que el usuario no ha hecho nada.

Si hay pasos previos para realizar las tareas, proporcione un enlace a la sección para realizar esos pasos previos. Por ejemplo, cómo iniciar sesión en el sistema. Si no tiene un inicio de sesión, cómo solicitar acceso al sistema. Nunca asuma que un usuario ya ha realizado esos pasos. Dígales dónde buscar esa información.

Proporcione siempre toda la información del documento, cada detalle. Por ejemplo, incluya la URL del sistema y no asuma que el usuario la conoce.

Recuerde que esta es una guía visual. Incluso la forma en que divide los pasos debe ser una señal visual para el lector.

Comience cada subsección con pasos. Cada paso debe constar de dos piezas complementarias, el texto y la captura de pantalla. El texto es un complemento visual de las capturas de pantalla, mientras que las capturas de pantalla son complementos visuales del texto.

Texto

El texto de cada paso debe contener los pasos numerados 1, 2, 3, etc. y contener instrucciones de texto sobre cómo realizar la tarea. Esto ayudará al lector a realizar un seguimiento de cada paso, dándoles un número para consultar cuando se hayan detenido.

Siempre me gusta hacer la tarea en cuestión mientras escribo para no saltarme ningún paso.

Recuerda no asumir nunca. Es posible que el usuario no conozca la URL de Google (sí, de verdad).

Puntos de bonificación si incluye pequeñas capturas de pantalla dentro del texto.

Este texto es bueno:

• Haga clic en el botón «Iniciar sesión».

Esto es mejor:

• Haga clic en el botón.

Esto proporciona una señal visual en línea para el lector, permitiéndole ver exactamente lo que buscará.

Capturas de pantalla

Cada captura de pantalla debe tener un borde. El usuario debe poder decir visualmente dónde termina su captura de pantalla y dónde comienza el documento, especialmente si la captura de pantalla y el documento tienen el mismo color de fondo.

¿Alguna vez ha leído un documento en el que las capturas de pantalla y la página son del mismo color? He leído demasiados y es todo un asalto a la vista. Así que sea amable con su lector para que pueda decir visualmente dónde comienza y termina todo.

La captura de pantalla debe brindarle al usuario un contexto y pistas visuales sobre dónde debe enfocarse. No es suficiente que hayas incluido la captura de pantalla; ahora debe enfocar al usuario. Existen múltiples estrategias para hacer esto. Mi herramienta de captura de pantalla favorita es SnagIt. Usted puede:

O una combinación de los mismos. Recuerde, desea proporcionar tantas señales visuales como sea necesario para que sea más fácil para el usuario. Sin embargo, use los efectos con moderación y use su mejor criterio. Mi regla general es que tres efectos deberían ser suficientes para enfocar la atención del usuario. Más solo distrae de las capturas de pantalla.

Cada paso y su captura de pantalla asociada deben tener sangría al mismo nivel. Si hay subpasos, la captura de pantalla del subpaso se debe sangrar al subpaso.

Dado que esta guía trata de hacerlo visual, debe tener suficientes capturas de pantalla de modo que si todo el texto del documento no estaba allí, el usuario debería poder realizar la tarea con solo mirar las capturas de pantalla.

Desea que el usuario pueda comprender exactamente lo que necesita hacer sin tener que leer el texto. Esa es la cantidad de capturas de pantalla que debe tener, tantas como sean necesarias. Un truco en la etapa de edición es poner el texto en blanco y ver si aún puede seguir las capturas de pantalla sin ninguna ayuda de texto para realizar la tarea.

En relación con eso, el texto también debe escribirse sin las capturas de pantalla en mente. Elimine las capturas de pantalla y vea si puede seguir las instrucciones y realizar la tarea solo con texto.

Ambos deben ser fáciles de seguir para que cualquier persona de cualquier rango de habilidad pueda completar la tarea. Si no está muy seguro de la dificultad de su texto, siempre puede pedirle a un amigo que lo lea, preferiblemente alguien que no entienda el material, y vea si puede comprender lo que está sucediendo. Si pueden entenderlo, ¡estás bien!

Mantenlo simple, tonto

En resumen, escriba guías de software con una página de título visual, una gran descripción, una tabla de contenido y secciones claras.

Escriba la tabla de contenido en forma de persona de modo que si un usuario no es esa persona, pueda omitir esa sección y centrarse solo en la sección que necesita leer para realizar su tarea.

En cada sección, incluya todo el texto y las capturas de pantalla que el usuario necesitará para realizar la tarea e, idealmente, realice la tarea mientras escribe la guía para que no se pierda nada.

Al hacer esto, es posible que reduzca parte de la carga de los usuarios finales, y ellos se lo agradecerán.