Escritura Técnica Clara y Efectiva
Clase 8 de 20 • Curso de Introducción al Technical Writing y Documentación de Código
Contenido del curso
En el technical writing la claridad es primordial por encima de todo. Es un tema indiscutible. Y para ello las frases son la unidad mínima en las que podemos expresar una idea. Tus frases deben ser claras y efectivas, así tus textos se entenderán mejor, el lector captará el mensaje fácilmente y tú harás gimnasia mental para ordenar tus pensamientos. Recuerda que a veces escribimos mal porque pensamos mal.
Hagamos una comparación con programar. Las buenas prácticas nos dicen que escribir líneas cortas de código facilita su lectura para otros. Además, es más práctico darle mantenimiento a líneas cortas de código que a líneas extensas. Esto aplica de la misma manera en el technical writing. La documentación corta es más fácil de leer y darle mantenimiento que a una documentación larga.
Te compartiré las bases para que aprendas a escribir tu documentación de manera corta, correcta, efectiva y, principalmente, con claridad.
Sé breve 🏃♀️
Iniciemos con esta frase del filósofo francés Blaise Pascal:
"Te escribo una carta larga porque no tengo tiempo de escribir una corta".
Y tiene razón. Es más difícil escribir frases cortas que frases largas. Redactar frases cortas nos obliga a organizar nuestro pensamiento y ordenar la información. El estilo breve es más exigente y requiere mucha disciplina, pero es la manera más eficaz para ser claros en nuestros textos.
Todo esto tiene que ver con nuestro pensamiento. Cuando tenemos que escribir sobre cualquier tema las ideas comienzan a dispararse, comenzamos a escribirlas en bruto y al finalizar tendremos frases kilométricas. Por sentido común, no podemos dejarlas así, tenemos que acortarlas para que nuestro lector no abandone nuestros textos.
Si tienes frases muy largas, es señal de que tienes material para sacar de ahí dos o tres frases breves. Tampoco tienes que escribirlas a manera de telegrama, hay que saber balancear, cada frase puede ser un concepto o una idea. Por otra parte, también debo mencionarte que es bueno agregar de vez en cuando alguna frase larga para no hacer monótona nuestra lectura, solo recuerda ser moderado al momento de usarlas.
Aquí te muestro un ejemplo de una frase muy larga con múltiples conceptos:
"El inventor de Linux es el ingeniero de software finlandés Linus Benedict Torvalds, quien llegó al mundo de la informática desde una edad muy temprana y estudió Ciencias de la Computación en la Universidad de Helsinki. Durante aquella época, él decidió adquirir un nuevo PC 386 -33 Mhz, 4MB de RAM (uno de los más avanzados de su época), sin embargo, a Linus no le gustaba el sistema operativo con el que trabajaba –Minix– y decidió crear uno él mismo".
Si dividimos esa frase larga en varias frases cortas sin romper la esencia de la idea, el resultado sería el siguiente:
"El inventor de Linux es el ingeniero de software finlandés Linus Benedict Torvalds. Ligado al mundo de la informática desde una edad muy temprana, estudió Ciencias de la Computación en la Universidad de Helsinki. Durante aquella época decidió adquirir un nuevo PC 386 -33 Mhz, 4MB de RAM (uno de los más avanzados de su época). Sin embargo, no le gustaba el sistema operativo con el que trabajaba –Minix– y decidió crear uno él mismo".
Usa verbos fuertes 😈
En el technical writing los verbos son lo más importante de una frase. Selecciona los verbos adecuados y el resto de la frase se da por sí misma. Quizá te tome tiempo elegir el verbo adecuado, pero una vez que lo hagas tendrás resultados satisfactorios. Trata de usar verbos precisos, fuertes y específicos.
Por ejemplo:
Elimina los "hay" 🙅♀️
No aburras a tus lectores usando la palabra "hay". Dales sujetos y verbos reales. Considera la siguiente frase de ejemplo:
Hay una variable llamada mensaje que almacena el mensaje que se mostrará al usuario.
Con un poco de trabajo podemos mejorarla, por ejemplo, de esta forma:
Una variable llamada mensaje almacena el mensaje que se mostrará al usuario.
Elimina o sustituye las palabras superfluas 🚫
Las palabras superfluas o de relleno son las que no tienen ninguna función dentro de nuestras frases. Son "comida chatarra" para nuestro lector. Es importante eliminar esas palabras o, en su defecto, sustituirlas. Con la práctica las irás descubriendo.
En este ejemplo cambiaré solo un par de palabras sin alterar su significado:
A pesar de que Gerardo no sabe programar, él sabe documentar software.
Aunque Gerardo no sabe programar, él sabe documentar software.
Escribe con las reglas de George Orwell 📖
Para finalizar quiero compartirte las reglas generales de escritura de George Orwell, las cuales también funcionan para el technical writing:
Estas reglas están escritas a manera de "lista", justamente el tema que veremos en el siguiente capítulo y un elemento de suma importancia dentro del technical writing. ¡Te espero allá!