¿Puede la escritura técnica apestar menos?

Lo primero que debe tener en cuenta acerca de la escritura técnica es que la gente no la lee por sí misma. Lo leen porque están tratando de hacer algo y necesitan más información. La escritura no necesita involucrar o entretener porque el lector ya está comprometido con la tarea. Es su compromiso con la tarea y su necesidad de información lo que los impulsa a seguir leyendo, no su compromiso con el texto.

Y por esta razón, la escritura técnica no debe intentar involucrar o entretener. Cualquier cosa que haga en esa área se interpone en el camino de lo que el lector quiere: obtener la información que necesita para volver al trabajo que estaba haciendo.

La sencillez y la claridad de la instrucción y la descripción son, por lo tanto, virtudes clave en la comunicación técnica. Sin embargo, eso no debería hacer que la redacción técnica sea un trabajo aburrido. Más bien, presenta un conjunto diferente de desafíos de escritura.

Hacer que las ideas, los conceptos y las tareas sean sencillos y claros es un desafío en sí mismo. Y debido a que el lector a menudo llega a la documentación con ideas falsas sobre cómo deberían funcionar las cosas, existe un verdadero desafío en cómo involucrarlos a ellos y sus procesos de pensamiento y cómo poner sus pies en el camino correcto, particularmente porque su actitud es "¡Solo dime qué botón presionar!"

Por último, recuerda que mientras que en todas las demás formas de escritura tu objetivo es atraer y mantener la atención del lector, en la escritura técnica el objetivo es que vuelva a lo que estaba haciendo lo más rápido posible. Cuanto menos tiempo pasen leyendo y más tiempo pasen con éxito, mejor será su redacción técnica.

Esta pregunta toca una de las ideas centrales de la escritura técnica: la autoría basada en temas .

Su ejemplo de paradigma, "1. enchufar 2. conectar 3. mirar". es una muestra del tema "tarea", pero también hay (al menos) otros 2 tipos, a saber, "concepto" y "referencia".

Agregar un tema de concepto breve que describa los beneficios de realizar los pasos 1-3 sería más atractivo y caería absolutamente dentro del ámbito de la redacción técnica.

La escritura técnica tiene como objetivo tomar la perspectiva del "usuario", sea lo que sea que estén "usando". Así que tiene el potencial de ser muy imaginativo y creativo.

Un ejemplo que me vino a la mente son las instrucciones o "reglas" de los juegos. Algunos de estos libros pueden ser tan atractivos que muchos fanáticos solo leen los libros de reglas sin jugar los juegos (sé que lo he hecho, y noto que las personas en los foros de discusión, por ejemplo, los juegos de rol, informan la misma fascinación).

Estoy fundamentalmente de acuerdo con @mbakeranalecta, pero discreparía amablemente de la idea de que el lector siempre está comprometido con la tarea que está explicando actualmente; parte del trabajo de escribir ayuda o preguntas frecuentes es ayudar al lector a descubrir qué problema tiene. en realidad tratando de resolver; cuanto más complejo sea el tema, más difícil será identificar su brecha de conocimiento y más imaginación se necesitará para llevar al lector de "allí" a "aquí".

Creo que lo que te falta es que toda escritura cuenta una historia. El hecho de que no haya una historia de amor o una persecución de autos no significa que su redacción técnica no esté contando una historia. Solo estás contando la historia de conectar un Chromecast. Esa es realmente una historia emocionante para las personas que acaban de obtener un Chromecast. ¡Son tus personajes! No disminuyas su entusiasmo con una escritura de mala calidad. Anímate con ellos: ¡estamos Chromecasting! — tal como te emocionarías con un personaje ficticio que se está enamorando o teniendo alguna aventura.

Comprenda correctamente, entre en la historia y luego escriba una guía agradable, concisa, útil, en un lenguaje sencillo y comprensible para todos para Chromecasting que es un placer leer y usar y que mejora la vida de las personas al hacer su nueva configuración de Chromecast en un evento divertido con tal vez una trampa menor aquí y allá que se resolvió fácilmente, en lugar de una tarea horrible que les robó horas de su preciosa vida y luego los dejó decepcionados.

En lugar de un personaje ficticio esperando que les digas qué hacer, tienes una comunidad de personajes reales esperando que les digas qué hacer. Puedes mejorar un millón de vidas con una gran escritura. Es una responsabilidad seria y una gran oportunidad para crecer como escritor y como persona.

Coincido con @mbakeranalecta en que el propósito de la redacción técnica no es entretener sino informar.

Recuerdo un libro de texto sobre desarrollo de software que tenía en la universidad donde el texto se interrumpía regularmente con pequeñas historias sobre "el primer día de Sally como programadora" y cosas por el estilo. Presumiblemente, estas historias tenían la intención de animar el texto mientras ilustraban puntos del capítulo. Personalmente, solo me hicieron sentir avergonzado por el autor. Las historias no solo eran en su mayoría irrelevantes, sino también aburridas y empalagosas. "¡Oh, qué emocionante es trabajar en el mundo real del desarrollo de software! exclamó Sally". Fue tonto.

Dicho esto, creo que puede ser bueno romper el tedio del material seco de vez en cuando. Escribí un libro de base de datos en el que conseguí que un dibujante dibujara algunas caricaturas para mí que CREO que no eran estúpidas, tal vez una para cada capítulo o dos. Una vez escribí una guía del usuario en la que en la sección que describía cómo agregar y eliminar usuarios del sistema, introduje la sección sobre cómo restaurar un usuario eliminado diciendo: "Si eliminas un usuario, y luego vienen arrastrándose rogando por su trabajo anterior, puede restaurar el usuario por..." Bueno, no es el tipo de broma que hará que la gente se ría a carcajadas, pero pensé que valía la pena reírse y ayudó a aligerar el estado de ánimo. Creo que ese tipo de cosas es útil.

Pero tendría mucho cuidado de no exagerar este tipo de cosas. Una pequeña broma cada diez páginas puede aligerar el estado de ánimo. Incluso si los chistes no son muy buenos, al lector probablemente no le importe. es un descanso Pero si lo hace constantemente, los lectores eventualmente dirán: "Oye, estoy tratando de aprender a operar un Foobar, no escuchar un montón de tus chistes tontos".

Diría primero que saques tu ego de la ecuación. La documentación técnica tiene un propósito específico, que es impartir información de una fuente autorizada a un lector. La información superflua, como el humor, es una distracción.

Digamos que quiero conectar mi reproductor de DVD a mi nuevo televisor de pantalla plana. No quiero escuchar acerca de cómo tu abuelo hizo caca de color cuando RCA lo presentó. ¿Cómo me ayuda eso a completar la tarea? Estos son los criterios para los documentos técnicos, en orden de importancia:

¿Es preciso? ¿Está completo? ¿Es apropiado?

Cíñete a la tarea ya los hechos. Si eres nuevo en el juego, encuentra un buen editor, con suerte uno que esté versado en el campo, y presta atención a sus comentarios.

Básicamente estaría de acuerdo con la respuesta aceptada de que el objetivo principal de la redacción técnica es ayudar a alguien en una tarea y debería centrarse en eso. (La mayoría de las veces) desea realizar un trabajo específico y rápido. Diría que la mayor parte de eso se aplica a la documentación en línea que debe ser concisa, como breves instrucciones o referencias.

Sin embargo, no estoy de acuerdo con que esto deba aplicarse a toda la documentación técnica y que siempre debe limitarse a la sequedad. No veo nada malo en estar informado y entretenido (si es posible).

Creo que hay varias maneras de poner un poco de diversión en la documentación.

• Use un buen diseño que haga que los documentos sean fáciles de leer y estéticamente agradables
• Agregue imágenes (y videos) para visualizar cosas
• El problema con el humor es que no todo el mundo lo aprecia. Pero, si conoces bien a tu audiencia, creo que no hay nada malo en un juego de palabras o un cómic de vez en cuando si encaja, ejemplo: https://pbs.twimg.com/media/DldA_cIXgAADj5w.jpg
• Otro ejemplo de concisión y diversión a la vista son algunas notas técnicas. La técnica puede ser útil para las hojas de trucos.
• Agregue analogías e imágenes para explicar las cosas, Ejemplo: una introducción a HTTP/2 para SEO

• Fuente: https://xkcd.com/293/
• Licencia: https://xkcd.com/license.html

Si tiene experiencia en programación, eche un vistazo a Kernighan y Ritchie .

¡Juro que la mitad de la razón por la que Unix se volvió tan popular fue la calidad verdaderamente asombrosa de ese libro y algunos otros como este! ¡Sé que definitivamente me inspiró!

En el otro extremo, intente consultar las páginas del manual de Unix/Linux, que, si bien son claras, casi nunca explican nada ni ofrecen ejemplos de uso.

Muchos programadores simplemente no quieren tomarse el tiempo para explicar cosas a seres inferiores, o les resulta muy difícil.

Una vez que sabe lo suficiente para diseñar e implementar algo, sabe mucho más de lo que cualquier usuario típico sabrá (¡o querría saber!) Se necesitan tantas facetas y habilidades básicas subyacentes que, para ser competente, muchas de convertirse en una segunda naturaleza o, para usar una de las palabras más perniciosas del idioma inglés, "obvio". Cuando estás cerca de algo como esto como programador (o de cualquier otra área intensa de especialización en la materia), cuando lo simplificas a lo que crees que son los conceptos básicos, aún puede ser incomprensible o al menos confuso para un usuario.

Además, probablemente no estaría trabajando en él si no entendiera ya qué problemas resolverá y por qué querría usarlo. Cosas como esta son asumidas por el programador incluso antes de que comiencen a desarrollarse y se vuelven algo inconscientes u "obvias".

Puede ser una tarea importante discernir lo que la mayoría de su audiencia probablemente sepa y comprenda y luego proporcionar las cosas que son necesarias para salvar el vacío entre ellos y la información técnica que está presentando.

Si presenta muy poco, entonces algunos lectores se perderán o serán desviados (vea muchas preguntas de SE donde las personas preguntan sobre esas pequeñas y lindas cadenas de galimatías que en realidad son bombas de horquilla, algunas de las cuales ya han colapsado la computadora del OP).

Si presentas demasiado, la gente dejará de leer, se sentirá insultada, se perderá en detalles irrelevantes o te murmurará cosas sobre TL;DR.

Es un logro muy especial (aunque por lo general ignorado y subestimado) escribir algo de tal manera que alguien que lo lea termine diciendo algo como "¡No sabía que podía hacer eso!", "Puedo ¡No esperes a probarlo yo mismo!, o "¡Ya veo!"

Puede que no tengas dragones para matar, pero si puedes hacer que alguien se sienta lo suficientemente seguro como para siquiera acercarse a un monstruo como gimp o inkscape (¡Ese es el tipo de cosas que suelo guardar en los armarios que tengo miedo de abrir!), Entonces eso es un gran problema.

Hay un gran espacio para los escritores técnicos que realmente pueden explicar y enseñar cosas, ¡no solo documentarlas!

Una forma que uso es hacer una pequeña broma en el medio. Como 1. Conéctalo. 2. Hazlo de nuevo, esta vez al revés, lo tienes. 3. Conectar. 4. Mira.

Burgess usó algo como esto en Earthly Powers . El protagonista había agarrado una pierna artificial y Burgess estaba describiendo cómo la estaba manejando como un arma (el punto técnico) y luego dijo que era como si fuera un vendedor de piernas artificiales y pensó algo como 'Aquí señora, mire la calidad de esta pierna, la mejor pierna que encontrarás' y luego la balancea hacia alguna persona. (Esta no es la cita exacta).

O puede escribir alguna descripción en el medio, como

X estaba leyendo el manual '1. Conéctese', decía. X lo enchufó. 'Bien. Siguiente paso ahora: 2. Conectar'. '¡Está bien! Conectémonos...'

etc.

Esto es algo que puede hacer con bastante facilidad y mantener el interés del lector.

La claridad en su redacción técnica siempre debe ser la máxima prioridad, pero eso no significa que deba sacrificar una conexión emocional con el lector.

Creo que tomaría un enfoque similar a la forma en que algunos sitios web copian la escritura. Como redactor, no se imaginaría que está contando la historia de Chromecast traicionando a la televisión. En cambio, imagina que estás escribiendo el diálogo para un solo rollo en un drama que se desarrolla en la vida de tu lector. Su lector es el personaje principal de esta historia. Usted, o más bien su manual, es el amigo útil. Lo grande, frustrante y técnico que están tratando de configurar es el antagonista.

Al escribir así, tenga en cuenta que la historia ya comenzó sin usted, antes de que el lector tomara el manual del usuario. Una vez que comiencen a leer, es tu trabajo esperar el estado emocional en el que se encuentran y tratar de amplificarlo si es positivo, o difuminarlo si es negativo.

Trate de pensar en la situación en la que se encuentra su lector. ¿Están frustrados porque no pueden hacer que algo funcione? ¿O están súper emocionados de que acaban de recibir un juguete nuevo con el que jugar? Ajuste su voz y tono para adaptarse a la situación probable. Es posible que incluso necesite ajustar su tono a lo largo del manual. Por ejemplo, la introducción puede ser alegre y entusiasta, pero una sección de solución de problemas puede cambiar a un tono más comprensivo.

No es necesario contar chistes ni agregar extras esponjosos que no muevan al lector hacia su objetivo. Pero sí necesitas entender quién es tu lector, qué está haciendo y por qué lo está haciendo. Con eso, puedes adivinar el tipo de persona de la que querrían ayuda en su situación actual: ¿papá? un médico de confianza? ¿Su amigo del trabajo que acaba de configurar su sistema ayer? Una vez que descubras quién es, usa la voz de esa persona. Piense en el nivel de formalidad de las palabras que está eligiendo y la complejidad de la estructura de su oración.

Si quiero que mi papá me explique algo, tal vez quiera detalles adicionales para poder aprender a hacerlo por mi cuenta. Si quiero que un médico me explique algo, espero un lenguaje más técnico (de hecho, si fuera demasiado simplista, ¡podría no confiar en el médico!) Si quiero que un amigo del trabajo me explique algo, podría esperar pasos simples para obtener hecho: oraciones completas pero sin detalles adicionales sobre por qué funciona.

MailChimp (un servicio de entrega de boletines en línea) se destaca por usar una voz consistente y amigable en todo su sitio web, incluso cuando se habla de aspectos técnicos. Ajustan el tono para adaptarse a las circunstancias para que los lectores nunca obtengan una broma cursi en un mensaje de error. Si bien pueden hacer bromas superfluas, nunca se interponen en el camino de la comprensión.

La Guía de voz y tono de MailChimp es un excelente lugar para comenzar a comprender cómo escribir de esta manera.

Un montón de grandes respuestas aquí. Uno de los mejores ejemplos de manuales de usuario creativos que he encontrado recientemente es este: http://jamhub.com/docs/JamHubOwnersManual_English.pdf

Han hecho un gran trabajo escribiendo para usuarios altamente técnicos que aman los detalles tecnológicos y no quieren que los hablen con desprecio, y usuarios de estilo 'plug play' que solo quieren comenzar con el producto pero se sentirían confundidos por el cosas tecnológicas.

¡Muestra lo que es posible cuando piensas en tu audiencia!

Espero que ayude.

¿Cómo animas la creación de contenido cuando escribes instrucciones técnicas? Bueno, obviamente no puedes usar demasiados epítetos o metáforas. Hay poco lugar para las emociones en los documentos técnicos. Sin embargo, algunas empresas están tratando de utilizar la escritura técnica como una herramienta para establecer o promover aún más la imagen de su empresa.

Un buen sentido del humor, por ejemplo, puede ser un rasgo por el que su empresa sea conocida. Y esto significa que incluso sus temas de ayuda pueden contener un par de bromas. Google, por ejemplo, hace eso en la documentación en línea. Sin embargo, Google tiene todo un equipo de expertos que están tratando de descubrir qué es lo apropiado. Además, estos expertos también están estudiando otras culturas para asegurarse de que las localizaciones cumplan con las especificidades éticas y culturales de los diferentes países.

No todas las empresas tienen los recursos que tiene Google, por lo que, para evitar dejar una impresión negativa, la mayoría de las personas optan por apegarse al lado más seguro de las cosas en sus manuales de usuario.

Le recomiendo que lea este artículo: ' Cómo aumentar el dramatismo en su documentación técnica ' para obtener más información sobre este tema.