¿Es posible que alguien que no es un profesional consiga una redacción de documentos técnicos clara, que resulte interesante para la audiencia general sin que esta se pierda entre datos y conceptos complejos?

Sí, se puede conseguir.

El problema está en que para escribir contenido técnico se necesitan conocimientos profundos sobre un tema. Algo que normalmente no va acompañado de la capacidad de simplificar, ya que la persona en cuestión sabe un montón del tema.

De hecho, esta persona habrá dedicado una vida entera a adquirir sus conocimientos técnicos, lo que le complica mucho explicarlos en pocas palabras.

Como llevo más de un año escribiendo contenido técnico sobre temas que se alejan mucho de mi área de conocimiento y he dedicado muchas horas a intentar comprender conceptos complejos, en el artículo de hoy quiero contarte mi experiencia a la hora de abordar la redacción de documentos técnicos. Si te encuentras en una situación similar o quieres aprender a redactar documentos técnicos que la gente sí lea, este es tu post.

Por qué los documentos técnicos son tan complejos

Cuando profundizas en un tema, sea cual sea, no haces sino descubrir que tiene más y más matices de los que habías imaginado.

Pongamos un ejemplo.

Modelos de atribución en marketing. Es un concepto sencillo: quieres saber a qué partida presupuestaria o acción debes atribuir los objetivos de tu campaña de, pongamos, captación de leads (contacto comerciales).

Un concepto en teoría sencillo, ¿no? El problema es que los modelos de atribución son tan escurridizos como las anguilas. Cuando empiezan a introducirse variables, las cosas se complican. Tanto que podríamos meter en una habitación a un puñado de expertos en analítica digital, cerrar la puerta y volver dentro de un año. Seguro que no han puesto de acuerdo.

Lo mismo sucede con los números.

Cualquier redacción de documentos técnicos puede caer fácilmente en el pozo de las estadísticas, evaluaciones, cifras y datos, que, seamos francos, te interesan a ti, pero a nadie más. Al menos no en grado de tentativa, que es como suelen utilizar los números los expertos. 😉

Ni que decir tiene que caerás también en la jerga. Los tecnicismos, a los que dediqué hace poco toda una entrada, son un arma de doble filo.

¿Qué puedes hacer entonces si eres experto en un campo y quieres crear documentos técnicos que no sean un galimatías sin sentido?

Ponte cómodo que allá vamos.

Cuándo, por qué y cómo utilizar correctamente la documentación técnica

Los documentos técnicos sirven para muchos propósitos, no solo para divulgar conocimiento.

Por ejemplo, pueden servir para que tus clientes utilicen y aprovechen al máximo tu producto, algo que puede conseguir que vuelvan a por más.

Son útiles además para conseguir autoridad entre tus colegas o captar nuevos clientes si tu producto es complejo.

Lo importante es que no frustre a tus lectores, sino que les ayude. Debe ser clara, sencilla y útil.

Estos son algunos ejemplos de cuándo utilizar documentos técnicos:

• Asistencia al usuario final: con documentos técnicos como guías de usuario, notas de la versión (para software), programas de formación o procedimientos operativos, cualquier cosa que ayude a los usuarios a usar tu producto.
• Soporte de marketing: en esta categoría se encuentran todos aquellos documentos que se centren en tu producto y que utilices para apoyar al equipo comercial de tu empresa, como vídeos explicativos, presentaciones o landing pages técnicas.
• Soporte para desarrollo: en algunas empresas, se elaboran manuales para ayudar a los empleados a desarrollar tu trabajo, como por ejemplo, los programadores.
• Soporte de la organización: por último, todos aquellos documentos técnicos que contengan información sobre la empresa, sus procedimientos, políticas o manuales para el empleado, se engloban en esta categoría.

Si hasta hace relativamente poco, todo este tipo manuales solía estar al alcance únicamente de los interesados o enterrada dentro de las empresas, hoy en día se suele encontrar en las webs o páginas de ayuda, lo que hace extensible todo lo que he comentado de SEO de contenidos en este blog a la documentación técnica.

Redacción de documentos técnicos que funciona, cómo planificar y ejecutar información que no mate de aburrimiento a la gente

Bien, queda claro que la redacción de documentos técnicos no se limita únicamente a soporíferos manuales que TIENES que leer, sino que puede servir a muchos propósitos que te acerquen a tus clientes y empleados.

¿Cómo redactarlos para que no maten de aburrimiento a la gente?

Lo primero que debes decidir es quién será el responsable de ellos. Como he comentado nada más empezar este artículo, lo más normal es que lo escriba un experto en la materia, alguien que sabe de lo que está hablando.

También lo puedes encargar (¡a mí! 🙋🏻‍♀️) a un redactor técnico que sea capaz de traducir el conocimiento complejo en algo que apetezca leer.

Con tu equipo de una, dos o más personas formado y motivado, es hora de ponerse a trabajar.

Paso 1/ Investiga y crea un “plan de documentación”

No es posible crear un manual de usuario de un producto que no conoces, igual que no puedes crear una guía para nuevos empleados si no trabajas en la empresa.

Ergo: escribe de lo que sabes.

Todo proyecto de escritura técnica comienza con una investigación. Puede sonar obvio, pero conocer de antemano el propósito y el alcance de tu documentación técnica te ahorrará un montón de tiempo y energía (y dolores de cabeza).

Si no eres experto en la materia, te toca hablar con los que saben o buscar la información que necesitas, del fabricante, de quien se encarga de esa área o de donde sea.

En resumidas cuenta, debes conseguir lo que en redacción de documentos técnicos llamamos “un plan de documentación”: un breve resumen que te ayude en el proyecto.

Debe incluir lo siguiente:

• Objetivos: ¿Qué quieres conseguir con este documento? ¿Qué la gente sepa cómo utilizar tu producto? ¿Una solución rápida que alivie el servicio de atención al cliente? ¿Usar ciertos aspectos de tu herramienta? Debes tener claro el objetivo, ya que de ello dependerán decisiones importantes como la longitud del documento o el tono que vas a utilizar.
• Recursos existentes: ¿Qué hay actualmente disponible? ¿Estás actualizando material o comienzas desde cero? ¿Hay versiones antiguas y desactualizadas que deben ser eliminadas? Revisa rápidamente con qué material cuentas para trabajar.
• Guías de estilo: soy una firme defensora de que toda empresa que escribe debe tener su propia voz. Eso significa crear una guía de estilo con pautas claras del tipo de lenguaje que se va a utilizar o qué términos deben prevalecer por encima de otros.
• Estructura: ¿Qué temas abordará la redacción de documentos técnicos? Piensa en esta parte como en el índice de cualquier otro documento, tratando de detallar todo lo posible para conocer la extensión del trabajo.
• Fecha límite: ¡lo peor de todo! ¿Para cuándo debe estar terminado? También de este detalle dependen muchas cosas, como la profundidad a la que puedes llegar.

Paso 2/ Estructura y diseña

El objetivo de cualquier documentación técnica es servir de ayuda. Por eso, debe tener una estructura lógica y fácil de usar. Antes siquiera de empezar a redactar, conviene que pienses cómo vas a presentar el contenido.

¿Qué significa esto?

Pensar en cómo vas a ofrecer contenido complejo de forma que resulte atractivo, como por ejemplo, con resúmenes, “take away”, a qué documentos vas a enlazar o te vas a referir, etc.

Aquí tienes algunos consejos que pueden ayudarte en esta fase:

Usa plantillas para un diseño consistente

¿Alguna vez has abierto un manual y te has dado cuenta rápidamente de que no serviría de ayuda?

Es probable que no se deba tanto al contenido como al diseño, por eso resultan tan fáciles los manuales de IKEA (al menos a mí).

Por eso los documentos técnicos deben contener información bien estructurada. Para que de verdad sea útil, este se debe presentar de forma fácil, accesible, y de manera que pueda analizarse rápidamente y encontrar lo que se necesita.

En la mayoría de los casos, esto significa usar algún tipo de plantilla o esquema. Por ejemplo:

• Título: ¿De qué va?
• Subtítulo: información adicional
• Resumen: ¿Qué vas a aprender?
• Tabla de contenidos: navegación del documento
• Características: cada sección del documento
• Lee también: documentos relacionados que pueden ayudar al usuario

Paso 3/ crea el contenido

¡Bien! Con tu plan y una buena estructura bajo el brazo, es hora de tomarse en serio la redacción de documentos técnicos.

Como cualquier otro tipo de formatos de redacción, la forma más fácil de aborda la documentación técnica es seguir ciertos pasos en lugar de comenzar a escribir sin más.

Esta es la forma más fácil de asegurarte de que lo que estás creando es de verdad útil, claro y de valor para tus lectores.

Comienza con un borrador de redacción de documentos técnicos

Con la información que has recopilado en tu plan de documentación, puedes esbozar un esquema de las partes más importantes a cubrir en cada una de las secciones.

Así, encontrarás rápidamente agujeros en la planificación y en la investigación.

En los manuales técnicos a los que me he enfrentado, me he dado cuenta rápidamente con este sistema de si me faltaba más material para equilibrar una sección o de si necesitaba más datos que complementaran las conclusiones esbozadas.

Estos son algunos consejos rápidos para escribir bien documentos técnicos:

• Escribir no es igual de fácil para todo el mundo. Me has oído decir que todo el mundo puede aprender a escribir de forma persuasiva. Y es verdad, pero no todos partimos de la misma casilla. Hay quien tiene un talento natural para la redacción y quien tiende a enrollarse o embrollar las frases. Cuenta con ello y ten paciencia contigo mismo.
• Escribe como un humano. Siento decirte esto, pero no hay un premio al mejor redactor de documentación técnica. No te vas a lucir. Tu premio es que los que leen el manual solucionen sus dudas o aprendan lo que deseas transmitir. Pero tampoco te pases. Todos hemos leído manuales que parecen directamente sacados de Google Translator. Si ves que te estás metiendo de lleno en frases largas y enrevesadas, aléjate. Vete a dar un paseo y vuelve con la cabeza fresca.
• No olvides que los lectores no son tú. Nos pasa a todos. Damos por supuesto que los que nos leen saben tanto como nosotros o se nos cuelan conceptos que ni siquiera un lector avanzado tiene por qué conocer. Nadie te va a criticar por incluir unos paréntesis con aclaraciones sobre conceptos complejos.
• Redacta lo que sea necesario y ni una palabra más. Si descubres que has alcanzado las 10.000 palabras, bien. No lo fuerces para que quede más completo. Como escribe el escritor técnico de Amazon, Tom Johnson: “un buen redactor técnico reduce el número de palabras a lo mínimo imprescindible para ser entendido”. Ni una palabra más.
• Recuerda el poder de las imágenes. Sí, es un cliché, pero las imágenes realmente valen más que mil palabras. Siempre que sea posible, visualiza lo que estás diciendo en lugar de intentar explicarlo.

Usa la regla 30/90 para conseguir feedback

Si tu manual técnico tiene muchas palabras, es probable que quieras saber cómo va. Tanto por tu tranquilidad mental como por la del lector, para asegurarte de que estás explicando las cosas como deben ser.

A menos que el experto en la materia seas tú, es conveniente que alguien que sepa mucho revise lo que estás escribiendo. No sería la primera vez que descubres que “implementar” no es lo mismo que “implantar”, por poner un ejemplo del mundo del software.

Aquí es donde puedes seguir la regla del 30/90.

Cuando has redactado el 30% del contenido, lo que pides es comentarios sobre el esquema, el tono y la profundidad. Cuando has redactado el 90%, es hora de meterse en faena y hacer los cambios más sutiles, como gramática, ortografía o reescribir alguna que otra frase que no esté completamente clara.

Edita, edita y edita

Un buen redactor edita una y otra vez su texto hasta que queda completamente pulido. El lenguaje debe tener una cadencia lógica y ser coherente en todo el documento.

Siempre que sea posible, debes intentar que, al menos, un par de personas más revisen tu contenido.

Paso 4/ entrega y testeo

Una vez que toda la documentación está reunida en solo lugar, es hora de recibir comentarios de personas reales para las que está concebida la guía o el manual.

Si ellos no lo entienden o lo encuentran aburrido, has fracasado.

Comienza por asegurarte de que los términos explicados corresponden con la realidad. Por ejemplo, que las instrucciones de uso que explicas en un manual de instalación no dejarán sin luz a toda la ciudad o que no se dañará el producto si el lector sigue las instrucciones que has redactado.

Haz exactamente lo que has escrito y a ver qué pasa. ¿Todo ok?

A continuación, realiza una auditoría de navegación. Recuerda que la estructura de tu documento es clave. Comprueba si hay enlaces rotos y asegúrate de que los elementos de navegación funcionen (en caso de que tu documentación técnica se presente en forma de página).

Por último, verifica los problemas de usabilidad. ¿Se pierden los usuarios? ¿No encuentras las respuestas que están buscando?

Tómate el tiempo necesario para realizar pruebas con usuarios externos que no sepan nada del proyecto, a ver cómo se manejan.

Paso 5/ crea un plan de actualización

Estás listo para lanzar la documentación técnica que tanto esfuerzo te ha costado. Si crees que tu trabajo está terminado, piénsalo otra vez.

Crea un plan de actualización

La documentación técnica es contenido vivo que debe revisarse y actualizarse con nuevos lanzamientos o actualizaciones de productos. Como parte de tu trabajo, debes crear un cronograma para su mantenimiento regular y actualizaciones.

Las 4 cualidades adicionales para una buen redacción de documentos técnicos

Si no ha quedado claro hasta el momento, lo único que necesita una buena redacción de documentos técnicos es claridad. La facilidad de uso debe ser tu máxima prioridad.

Pero no es la única, además, debe tener:

• Debe ser fácil de usar. El contenido duplicado, una estructura deficiente o un proceso poco claro pueden ser la tumba de la mejor documentación del mundo.
• Debe estar actualizada. No tiene sentido dar a sus usuarios información inexacta o mostrarles capturas de pantalla con fecha de hace dos años. Mantén siempre la documentación técnica actualizada.
• Diseña con cabeza. Cada punto de contacto del usuario con tu marca es una oportunidad para definirla, incluso con este tipo de documentación. Haz que el diseño sea coherente con el estilo y el diseño de la marca.

Accesible desde cualquier lugar. El móvil se ha apoderando del mundo. Tu documentación técnica, al igual que el resto de tu web, debe proporcionar una gran experiencia para los usuarios en todos los dispositivos.