¿Cuáles son las habilidades clave para un nuevo escritor técnico?

Saber quién es tu audiencia es un buen primer paso. Escribir documentación para el usuario final no es lo mismo que documentar una API y no debe abordarse de la misma manera. Tu audiencia define todo lo que viene después y cuán simple necesitas presentar los conceptos.

Como señaló Lauren, escribir simple y llanamente es un consejo sólido, sin importar quién sea su audiencia. La simplicidad está determinada por su audiencia, pero el lado "simplemente" no lo está. En líneas similares, las imágenes, los diagramas y las capturas de pantalla son maravillosos. Nunca digas con palabras lo que puedes ilustrar con una captura de pantalla. Elimine cualquier cruft de una captura de pantalla que sea tangencial o que pueda distraer la atención del mensaje. Creo que este es un ejemplo decente de mis propias cosas personales que demuestra una combinación adecuada de ilustración con texto y recortes.

La mayor parte del trabajo que hago es la documentación del usuario final. Como tal, trato de tener a mi mamá en mente cuando lo escribo. Es inteligente, pero no técnicamente inclinada. ¿Podría ella entender los conceptos y hacer lo que estoy explicando?

Algunas cosas a evitar:

He notado que muchos desarrolladores de software usan palabras como "trivialmente", "obvio" y otro vocabulario desagradable cuando escriben contenido técnico. Esto es malo. No estás haciendo demostraciones matemáticas; no hay QED en la comunicación técnica. A nadie le importa lo inteligente que seas o lo fácil que te resultó encontrar la solución. Llegué al punto en que simplemente cierro la pestaña del navegador si veo demasiado de esto.

El perfeccionismo es otra trampa. La escritura técnica debe ser lo suficientemente buena. No necesita ser perfecto. No estás tratando de ser James Joyce. La comunicación técnica se trata de realizar una tarea, no de ganar el Pulitzer. (¡No es que no debas tratar activamente de mejorar en tu oficio!)

No incluya demasiados detalles, a menos que deba hacerlo. Esto se remonta nuevamente a su audiencia, pero su trabajo como escritor técnico no es impresionar a los ingenieros que construyeron el sistema con lo inteligente que es. Estaba escribiendo documentación para un cliente de iOS hace unos meses y comencé a explicar cómo funciona el back-end en la guía de inicio rápido. El desarrollador mencionó que el primer borrador era un poco más complicado de lo que buscaba, y tenía razón. A los usuarios finales no les importaba cómo el cliente elegía un modo de conexión; solo querían que funcionara. Guarde esas cosas para la documentación detallada que se colocará en un KB, no en una guía de inicio rápido. Del mismo modo, lo que encuentra interesante sobre lo que está documentando no es necesariamente lo que la audiencia encontrará útil. El avance del alcance no se limita solo a los proyectos de ingeniería.

Evite dispositivos que distraigan de su mensaje. Si le está diciendo a alguien cómo configurar el reloj en su VCR (je), no necesita contarlo en forma de historia. Me siento ridículo por siquiera mencionar esto, pero lo he visto hacer (!).

Sea claro. Escribe simple y claramente. Defina su jerga y sus acrónimos, incluso si cree que todos ya los conocen, y use la jerga con la mayor moderación posible.

Imagina entregar tu documento a alguien fuera de tu campo (o mejor aún, trata de conseguir un editor fuera de tu campo) y apunta a que tu trabajo tenga algún sentido para esa persona. Obviamente, un documento técnico extremadamente sofisticado no va a tener mucho sentido para un profano, pero esa persona al menos debería ser capaz de captar la esencia de lo que estás diciendo.

Suponiendo que escriba otras cosas (id est, suponiendo que tenga facilidad de expresión escrita), hay cuatro habilidades para pulir que se aplican a toda la escritura técnica.

• Simplicidad a través de la división: Rompe ideas complejas en muchas simples.
• Simplicidad a través del vocabulario: use palabras cotidianas siempre que sea posible sin sacrificar la precisión.
• Simplicidad a través de la organización: configure el texto de manera que cada concepto esté fácilmente respaldado por conceptos explorados previamente.
• Simplicidad a través de la pulcritud: desarrolle una forma discreta de explicar los términos. A veces un pie de página es una distracción, a veces es lo más adecuado.

A través de la práctica y la observancia de esos principios, el material técnico puede convertirse en un material de lectura agradable.

Después de desarrollar esas habilidades, hay algunos pasos (no habilidades) que debe seguir para ser un buen escritor técnico. Otros que respondieron antes que yo mencionaron algunos de ellos (como conocer a tu audiencia), pero como creo que ese no es el espíritu de la pregunta, no los abordaré. Son, por supuesto, clave para escribir con éxito artículos técnicos, por lo que también debe prestar atención a esas respuestas.