Este artículo no implica ningún consejo rebuscado o poco obvio para redactar o revisar la documentación técnica. Muchos de los «consejos» enumerados aquí parecen obvios. Sin embargo, al analizar los manuales de nuestros clientes, encontramos los mismos errores triviales que se producen, por lo general, por un simple olvido. Por lo tanto, esta publicación puede considerarse como un recordatorio para los editores inexpertos.
Espero que disfruten de su lectura.
Después de un largo periodo de tiempo trabajando con un programa para la edición de manuales de usuario, nuestro equipo ha revisado y analizado muchos proyectos externos, cuyos líderes han recurrido a nosotros en busca de ayuda. La mayoría de las veces, nos hacían preguntas sobre la implementación de ciertas técnicas en la documentación de usuario de sus productos. Y, sobre la base de esta experiencia, sacamos dos conclusiones:
1) La documentación de usuario es necesaria y la gente la lee.
2) Si no se usa, se debe a los siguientes motivos:
Parte uno
¿Dónde se encuentra el manual de usuario?
• En el sitio web del software no hay ningún enlace al archivo de ayuda.
Todo el mundo sabe, desde hace mucho tiempo, que lo ideal es publicar el manual de usuario en el sitio web, pero a veces uno se olvida de crear en el menú un botón específico con un enlace a la documentación de ayuda. La solución a este problema es obvia: añada el manual de usuario al menú de su sitio web para que nadie sufra buscando la «ayuda».
• La documentación de ayuda es difícil de encontrar.
Sí, el error es similar al anterior, pero se diferencia en que el desarrollador no se olvidó de proporcionar un enlace a la documentación de ayuda, sino que decidió que el usuario podría encontrarlo fácilmente en algún lugar escondido del sitio web. Y eso no es así. El usuario es perezoso, recuérdelo. Simplemente añada un enlace a la documentación de ayuda en algún lugar destacado.
• Falta la «Ayuda» en el menú.
La solución es simple: eche un vistazo a la interfaz del programa e intente encontrar un lugar para los elementos de control que abrirían el archivo ayuda.
• ¡«F1 no funciona!».
Tradicionalmente, la ayuda contextual se activa al presionar la tecla F1. Por lo tanto, los usuarios presionarán esa tecla en primer lugar y, si no funciona, lo más probable es que crean que la documentación de ayuda simplemente no existe en su programa.
Le pasa algo al formato
• El formato del archivo no se admite.
Este error lo suelen cometer los clientes que desarrollan programas aptos para varias plataformas. Al crear un archivo de ayuda, a menudo olvidan que no todos los usuarios usan Windows, e incluyen la documentación de ayuda de su producto solo en formato CHM. Este formato es perfectamente compatible con Windows. Sin embargo, CHM no es «nativo» para otros SO, y el cliente tendrá problemas al intentar abrirlo en MacOS o Ubuntu.
• El formato del documento no se puede leer en un dispositivo en particular o en un entorno concreto.
A simple vista, uno podría pensar que los formatos HTML y CHM son una solución universal para los manuales de usuario. Al tener acceso a Internet, la documentación de usuario publicada en el sitio web se puede abrir desde cualquier plataforma, y la ayuda contextual se puede abrir con tan solo presionar la tecla F1.
Sin embargo, cabe recordar que el usuario podría no tener acceso a Internet y es posible que necesite recurrir a la documentación de ayuda fuera del programa.
La solución es simple: proporcione su producto junto con un manual de usuario en formato PDF, o publique este archivo PDF en su sitio web para que los usuarios puedan descargarlo en su dispositivo. En este caso, el usuario siempre tendrá a mano una versión local del manual que podría consultar para obtener ayuda.
Problemas de navegación
• Falta la barra de búsqueda en la documentación de ayuda.
La documentación técnica del producto en sí implica una gran cantidad de secciones, e incluso con una estructura buena y lógica, será difícil que el usuario encuentre la información que necesita. En este caso, le puede ayudar la opción de «buscar» en el documento. Pero tanto en formato PDF como en CHM, la función de búsqueda está implementada por defecto. Entonces, ¿por qué se da el error?
Porque los desarrolladores a menudo se olvidan de la documentación en línea, que representa un conjunto de diferentes archivos HTML. En el manual en línea, el navegador puede encontrar frases específicas solo en la página que está abierta. Para buscar en todas las secciones de la documentación, debe crear un script especial o utilizar Google Site Search.
• Una mala organización de la documentación o su completa desestructuración.
Parece increíble, pero cierto: todavía nos encontramos con archivos de ayuda en los que la información se presenta en forma de texto continuo y no se divide en secciones.
El manual de usuario no es una obra artística en la que la información fluye siguiendo un «guion». Los usuarios buscan
soluciones a problemas específicos en la documentación de ayuda, y es muy difícil encontrar la información requerida en medio de texto fluido, aunque se recurra a la combinación Ctrl+F.
Dé una buena estructura a su manual de usuario. Divídalo en secciones y publíquelas en el orden en que el usuario se vaya a familiarizar con el producto. Para ponérselo más fácil, fíjese en los manuales de productos desarrollados por grandes empresas. Será mucho más rápido y cómodo elaborar la documentación de ayuda si sigue un ejemplo.
Además, trabajar en un proyecto con una estructura lógica y bien pensada resulta mucho más fácil, especialmente cuando necesite actualizar y complementar la documentación de ayuda.
Y antes de terminar la primera parte del artículo, me gustaría señalar el software que, como mencioné anteriormente, vengo desarrollando desde hace muchos años: Dr.Explain.
Puede resultarle útil crear un manual de usuario de forma más fácil y rápida.
¡Gracias!
Top comments (0)