6 principios de redacción técnica para hacer tu documentación más fácil de usar

Una documentación fácil de usar es la documentación ganadora para cualquier escritor técnico. Pero crear una puede resultar complicado, sobre todo si estás escribiendo para un público diverso con diferentes ubicaciones e idiomas. Estos son algunos sólidos principios de redacción que te servirán de guía siempre que busques redactar materiales fáciles de usar por los usuarios.

Principios de redacción técnica para crear documentación fácil de usars

Examinemos estos principios más a fondo…

#1. Clarifica los conceptos complicados más que cualquier otra cosa

Una de las principales razones por las que muchos usuarios de productos no se leen los archivos de ayuda es la jerga técnica que contienen. Lo que a ti como escritor técnico te puede parecer una terminología sencilla, puede ser uno de los conceptos más complicados a los que se hayan enfrentado algunos usuarios.

Así que si tienes un proceso o cualquier otra cosa que resulte muy complicada, la menor manera de explicarla a los usuarios es con frecuencia mediante ejemplos. Cada ejemplo ofrecerá más claridad a tu contenido.

Por ejemplo, si añades tres ejemplos para aclarar un concepto o término confuso, los usuarios lo entenderán mejor que si te limitas a añadir un solo ejemplo.
Dicho esto, no todo concepto o término necesita un ejemplo. Pero recuerda siempre que los ejemplos son una importante herramienta de tu caja de herramientas de escritor técnico para comunicar información compleja de un modo fácil de entender para los usuarios.

#2. Equilibra los textos con contenido visual

Los manuales y documentos de ayuda no tienen por qué ser aburridos. Si quieres que tu documentación resulte atractiva, añade elementos visuales. Hay varias opciones entre las que elegir, como flujos de trabajo, capturas de pantalla con anotaciones, diagramas, ilustraciones o simples imágenes; los elementos visuales añaden mucho a las documentaciones.

Los visuales equilibran los textos, ofrecen un formato diferente para entender mejor, conectan con los modos visuales de aprendizaje del cerebro humano y son una guía de referencia para los usuarios al realizar tareas. Algunos visuales son aburridos de crear, pero merecen absolutamente la pena.

Dicho esto, si tienes pensado traducir tu documentación y todos los idiomas se traducen por igual, o si tu intención es centrarte más en ejemplos de código que visuales, quizá solo necesites algunas imágenes para tu contenido. Pero esto no quiere decir que no debas esforzarte por comunicarte por medio de elementos visuales siempre que sea posible. Recuerda que los elementos visuales te permiten comunicarte prácticamente con cualquiera, incluso sin textos.

#3. Sé el primero en poner a prueba tus instrucciones

Puede resultar difícil evaluar los materiales de ayuda que has creado a menos que recorras las instrucciones y realices las tareas tú mismo. Poner a prueba las instrucciones personalmente parece algo evidente, y en el caso de las documentaciones de GUI, normalmente lo es. Sin embargo, en realidad puede resultar complicado hacerlo.

Pero resulta bastante sencillo determinar si un escritor técnico ha redactado una documentación basándose exclusivamente en información que alguien ha compartido con él, en vez de información recopilada de primera mano por el escritor técnico. Haz siempre todo lo que puedas por recorrer y poner a pruebas las instrucciones tú mismo.

#4. Utiliza Aseguramiento de Calidad para obtener ejemplos de lo que estás documentando

Las personas de Aseguramiento de Calidad deberían ser tus mejores amigas si eres escritor técnico. Estas personas siempre conocen el sistema mejor que nadie. Configuran entornos de prueba para garantizar la funcionalidad y a menudo tienen un conjunto de ejemplos prácticos (funciones a probar) para cada lanzamiento.

Por ejemplo, si estás documentando una API, los ingenieros de calidad quizá ya tengan las llamadas a probar en formatos listos para usar. Aprovechar los recursos de calidad puede facilitar enormemente la redacción de documentación.

Sin embargo, en algunos casos, Aseguramiento de Calidad puede no tener la información empresarial de más alto nivel sobre los diferentes escenarios en los que se utilizarán las funciones. En muchos casos, la única prueba es si la función funciona o no. Quizá tengas que consultar a jefes de producto para obtener una perspectiva de mayor nivel del uso que tendría la función. No obstante, trabajar con tu equipo de Aseguramiento de Calidad puede facilitar muchísimo tu trabajo.

#5. Incorpora las opiniones de los usuarios en tu evaluación

Necesitas conseguir comentarios directos de los usuarios para entender el valor real de tus documentaciones. No puedes llegar a conclusiones lógicas basándote en presunciones. Que los usuarios entiendan o no la documentación, que la misma satisfaga sus necesidades, etc., se reduce a un juego de adivinanzas a no ser que consigas opiniones más tangibles de las personas a las que realmente van destinados los productos de ayuda.

Aquí puedes leer más sobre análisis de público en escritura técnica, cómo hacer las cosas bien.

Debido a la necesidad de incorporar opiniones de usuarios, deberías pensar en tener algún tipo de interacción (que puede ser directa a través de centralita, redes sociales o foros) para evaluar adecuadamente el material de ayuda. Recuerda siempre que es difícil evaluar tu archivo de ayuda únicamente a partir de tu experiencia. Esta es una de las 5 habilidades principales que necesitarás para convertirte en un gran escritor técnico.

Incluso si has probado todas las instrucciones y realizado las tareas, es posible que estés demasiado familiarizado con las instrucciones y las recorras con facilidad. O puede que te falten piezas importantes de información necesaria, o quizá hayas malinterpretado las plataformas o escenarios de implementación.

#6. Publica tus materiales de ayuda en formatos fáciles de usar

No limites tus materiales de ayuda a uno o dos formatos solamente. Los usuarios a menudo tienen acceso a varios tipos de dispositivos o sistemas operativos diferentes. Para empezar, puedes consultar los 7 mejores formatos para publicar tus materiales de ayuda.

Puedes utilizar una herramienta de creación de documentación de ayuda como HelpNDoc para crear documentación y publicar tu contenido en varios formatos diferentes, entre ellos documentos Word y PDF imprimibles, documentación basada en páginas web, archivos de ayuda CHM Help de Windows, páginas web específicas para iPhone, eBooks ePub y Kindle o archivos de ayuda Qt Help interplataforma. Y lo mejor de todo es que HelpNDoc es gratuito para uso personal y de evaluación.

¡Disfruta creando documentación!

Ver también...

Como crear documentación online atractiva

Es fácil asumir que el contenido es el único elemento por el que se preocupan los usuarios cuando utilizan documentación de ayuda. Pero esta conclusión está muy lejos de la realidad. El diseño es uno …

Lee Mas →

Consejos para redactar guías de usuario online

Los manuales y guías de usuario online son muy cómodos para los usuarios ya que les permiten acceder fácilmente desde casi cualquier parte. Por ello, las guías de usuario y manuales online deben estar …

Lee Mas →

7 razones clave por las que necesitas una página web HTML dinámica

¿Te encantaría que tu página web tuviese un aspecto fantástico, con una experiencia de usuario más rica y asombrosa en todos los dispositivos, plataformas y tamaños de pantalla? Es fácil llegara la …

Lee Mas →

Por qué los usuarios no leen tus manuales y cómo lograr que lo hagan

Has diseñado un producto prácticamente perfecto o creado un gran programa de software. Después, has contratado a algunos de los mejores escritores técnicos para escribir un manual de ayuda fácil de …

Lee Mas →