Estrategias para redactar documentación técnica eficaz

He estado escribiendo artículos técnicos de un tipo u otro desde 1999, cuando hacía control de calidad para la sucursal de I+D de Altec Lansing en Kfar Saba, Israel. En aquel entonces, sacábamos dispositivos innovadores relacionados con el audio, como (jadeo) dispositivos de audio USB que funcionaban en Windows ME y 2000. Tenían errores y configurarlos no era tan sencillo como lo es hoy.

Necesitábamos médicos.

Teníamos algunos obstáculos que los usuarios tenían que superar y necesitábamos una forma de documentar cuáles eran, cuáles eran los casos extremos y cómo diagnosticar y solucionar todo eso. Tenía que estar bien empaquetado, con un formato limpio y accesible para los usuarios que instalaron nuestra aplicación auxiliar. Encontré la aplicación Robohelp, que se utiliza para crear aplicaciones de ayuda estándar en Windows, y agregué un archivo de ayuda a nuestra instalación.

Durante nuestro proceso de control de calidad, identificábamos los problemas, documentábamos lo que pensábamos que era destacado y lo organizábamos en el archivo de ayuda que venía incluido con el dispositivo. Yo tenía 19 años en ese momento y no tenía ninguna experiencia con estas cosas, y fue un proceso inmensamente ingenuo. No obstante, sentí que era lo correcto para nuestros usuarios y mi gerente no me dijo explícitamente que no lo hiciera.

Han pasado 24 años y desde entonces he documentado varios proyectos. La escala ha crecido y la forma en que veo ese tipo de proyectos ha cambiado sustancialmente.

Tengo algunas ideas sobre lo que hace que sean buenos médicos y me encantaría compartirlas contigo si estás interesado.

Concepto básico de documentación

Me gustaría comenzar con un conjunto de reglas más concretas que creo que son fundamentales para el éxito de un producto de documentación.

• Los médicos deben usar palabras pequeñas para describir grandes ideas , así que no uses palabras florituras ni oraciones complejas para describir lo que se puede decir en términos más simples. Perderás usuarios en el camino y no vale la pena el ego de tu escritor.

• Los documentos deben contar una historia cuando sea posible , porque un conjunto de tareas personales y con las que se pueda identificar que cuentan una historia serán más atractivos y memorables para el usuario que un conjunto abstracto de instrucciones.

• Los documentos deberían poder buscarse , porque en serio: esto es una obviedad. Si no es fácil encontrar cosas en sus documentos, sus usuarios no encontrarán lo que necesitan.

• Los documentos casi siempre son parte de una estrategia más amplia , y esto es especialmente cierto cuando se trata de productos de software. Esto toca el tema más amplio de la defensa de los desarrolladores, pero en resumen: sus documentos deben estar respaldados por tutoriales en vídeo, ejemplos de uso real y soporte técnico en vivo.

• Los documentos deben probarse , porque puede estar seguro de que todo está bien, pero sin usuarios reales, como ocurre con cualquier otro producto, no lo sabrá con certeza. Pruébalo y pruébalo de nuevo.

  
  

Los documentos holísticos son productos bien diseñados

Cuando aprendes un nuevo lenguaje de programación , los conceptos e ideas de ese lenguaje fluyen hacia tu bolsa de trucos para la resolución de problemas. Te convierte en un mejor desarrollador de software y, al final del día, creas un mejor software porque eres más consciente y capaz.

Mi carrera ha sido complicada e incluyó mucho diseño de productos de software, desarrollo de software, soporte técnico y defensa de los desarrolladores. Cada disciplina ha influido en cómo pienso y me acerco a los demás.

Cuando abordo un proyecto de redacción técnica, es con esta visión amplia de lo que un usuario va a necesitar. Creo que esa es la forma correcta de pensar sobre los médicos: de manera integral. Los documentos no están bien definidos y para crear buenos documentos hay que ser flexible.

Para mí, eso significa que debes pensar en tus usuarios desde tantos ángulos como sea posible. No puedes dar nada por sentado o vas a decepcionar a algún grupo de usuarios de una manera que afectará negativamente a tu marca, tu producto o tu negocio de una manera de la que será difícil recuperarse.

Sus documentos suelen ser una experiencia decisiva para sus usuarios.

Si hace un buen trabajo, sus usuarios utilizarán su producto con éxito y se convertirán en defensores de su marca. Si no lo hace, probablemente nunca volverán a usar su producto porque sus médicos les dejaron un mal sabor de boca. También se lo harán saber a los demás. El buen marketing comienza aquí, así que tenlo en cuenta.

Haciendo buenos doctores

Hacer buenos documentos simplemente significa que debes abordar la creación de tus documentos como lo harías con cualquier otro proceso de producto.

Necesitas:

• Sepa por qué está creando sus documentos
• Sepa quién es su público objetivo
• Sepa cuáles son sus puntos débiles
• Mejore sus documentos con el tiempo

Echemos un vistazo más de cerca a cada uno de estos.

Saber el por qué de sus documentos suele ser una pregunta y una respuesta muy sencillas que se encuentran en la superficie. Está creando documentos porque, si no lo hace, los usuarios quedarán olvidados y no podrán utilizar su producto. En un nivel más profundo, existe una respuesta específica para su caso de uso. ¿Tiene una herramienta de desarrollo? Ese es un conjunto de respuestas. ¿Tiene una herramienta de diseño minorista? ¿Tiene un producto SaaS de contabilidad? ¿Tienes una cafetera automática? Todos estos son conjuntos de respuestas separados.

La forma de sus documentos se describe según quién los utilizará. ¿Está en línea? ¿Viene incluido con una aplicación? ¿Está impreso? Cada base de usuarios necesitará algo más y debes tener claro desde el principio quiénes son.

Su trabajo es descubrir qué es difícil para cada uno de sus usuarios y elaborar sus documentos para canalizarlos a través de contenido informativo que resuelva su problema específico.

Lo más importante es que debes saber que probablemente no lo harás bien la primera vez. Eso significa que sus documentos deben mantenerse y actualizarse a medida que sus productos crecen y cambian con el tiempo. Con suerte, esto se hace dentro de algún marco que permita una fácil comunicación con los usuarios a los que intenta ayudar. Debe hablar con sus usuarios, escuchar sus necesidades e intentar utilizar sus documentos para mejorar su experiencia al utilizar su producto.

Sus documentos son una parte integral de su éxito

Resumiré simplemente subrayando la importancia crítica que tienen los documentos. Sin ellos, sus usuarios están solos y deben valerse por sí mismos.

Esto siempre significará menos casos de éxito, peores vistas de su producto dentro de su ecosistema, más desarrolladores o usuarios descontentos y un impacto negativo en su marca o empresa.

Los documentos son un subproducto importante por derecho propio, son una inversión y deben ser parte de su estrategia de producto más amplia.