En el Curso de Escritura Online podemos profundizar muchísimo más en las buenas prácticas de redacción y escritura para internet. :run:
Introducción al Technical Writing
¿Qué es Technical Writing? Lleva tu documentación al siguiente nivel
Habilidades para convertirte en Technical Writer
¿Conoces a tu público? Escribe específicamente para tu audiencia
Cómo entrevistar equipos de programación para recolectar información técnica
Estructura gramatical
Un repaso por la gramática básica
Voz activa vs. voz pasiva: estándares y estructura de una oración
Uso correcto de acrónimos y abreviaturas para explicar términos desconocidos
Técnicas de escritura fundamentales para documentos técnicos
Sigue las reglas de George Orwell para escribir con claridad
Uso correcto de listas y tablas para ordenar información
Tipos de párrafos y paso a paso para estructurarlos
Conceptos básicos de programación e ingeniería de software
¿Qué es programación? Evolución de la documentación y technical writing
Lenguajes de programación, tipos de datos y estructura de documentos HTML
Estándares de documentación de código
Cómo documentar una función de código
Buenas prácticas de legibilidad para código y comentarios
Organización y revisión de tu documentación
Organiza y define el alcance de tus documentos
Utiliza Markdown en documentos técnicos
Guía para revisar documentación en equipo de manera efectiva
Cómo organizar documentos largos
Diseño de documentos
Crea ilustraciones instructivas
Conclusiones
Siguientes pasos para convertirte en Technical Writer profesional
Sigue las reglas de George Orwell para escribir con claridad
8/20Lectura
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:
- Verbo débil: Este bug pasa cuando…
- Verbo fuerte: El sistema muestra un bug cuando…
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:
- Nunca uses una palabra larga cuando una corta funciona.
- Si es posible recortar una palabra, hazlo.
- Nunca uses la voz pasiva, usa la voz activa en su lugar.
- Nunca uses una frase extranjera, una palabra científica o de la jerga si puedes pensar en un equivalente del inglés -o el idioma en el que redactes tu documento- cotidiano.
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á!
Aportes 16
Preguntas 0
Ordenar por:
Las reglas de George Orwell me recordaron al “Zen de Python”:
The Zen of Python
Beautiful is better than ugly.
Explicit is better than implicit.
Simple is better than complex.
Complex is better than complicated.
Flat is better than nested.
Sparse is better than dense.
Readability counts.
Special cases aren't special enough to break the rules.
Although practicality beats purity.
Errors should never pass silently.
Unless explicitly silenced.
In the face of ambiguity, refuse the temptation to guess.
There should be one-- and preferably only one --obvious way to do it.
Although that way may not be obvious at first unless you're Dutch.
Now is better than never.
Although never is often better than *right* now.
If the implementation is hard to explain, it's a bad idea.
If the implementation is easy to explain, it may be a good idea.
Namespaces are one honking great idea -- let's do more of those!
¡Pensaría que estas oraciones se pueden reducir aún más!
A pesar de que Gerardo no sabe programar, él sabe documentar software.
Aunque Gerardo no sabe programar, él sabe documentar software.
Quedaría mejor (en mi opinión):
Gerardo no sabe programar, pero sabe documentar software.
O si el contraste entre lo que sabe y no sabe no es importante para el caso, podría quedar:
Gerardo no sabe programar, sabe documentar software.
¡Saludos! 😄
¿Cómo sabes si un verbo es fuerte o débil?
Lo que yo hago cuando no sé ordenar las ideas es ir escribiendo lo que me salga de la mente. Luego lo leo y veo qué ideas se pueden integrar en otra misma o definitivamente arreglarlas, por ejemplo:
Para empezar qué es la ansiedad y cuáles son los síntomas.
Pasa que durante la adolescencia incrementa, más que nada he notado que entre los 16 y cuando vamos a cumplir 18, la ansiedad.
**Empezamos a crear dudas existenciales, pero más que nada, pensamos que ya al ser mayores, nuestra vida se acaba.
Otra parte, es que al ir habiendo cambios, empezamos a deprimirnos, ansiedad, dudas existenciales, ya que antes no teníamos tal vez la percepción de la realidad que ahora, evidentemente, nos vamos convirtiendo en adultos y vemos una vida llena de obstáculos.**
Y queda así:
Introducción, qué es la ansiedad y síntomas.
Pasa que durante la adolescencia incrementa, más que nada he notado que entre los 16 y cuando vamos a cumplir 18, la ansiedad.
Otra parte, es que al ir habiendo cambios, empezamos a deprimirnos, ansiedad, dudas existenciales, ya que antes no teníamos tal vez la percepción de la realidad que ahora, evidentemente, nos vamos convirtiendo en adultos y vemos una vida llena de obstáculos y por ende, pensamos que nuestra vida acaba ahí, en los 18.
Esto me ayuda mucho para que no se me olvide y para mejorar su comprensión.
Me llamo poderosamente la atención.
Nunca uses una palabra larga cuando una corta funciona.
Si es posible recortar una palabra, hazlo.
Nunca uses la voz pasiva, usa la voz activa en su lugar.
Nunca uses una frase extranjera, una palabra científica o de la jerga si puedes pensar en un equivalente del inglés -o el idioma en el que redactes tu documento- cotidiano.
📌 Súper importante:
.
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.
La escritura con buena otorgrafía también establece la preparación ante el tema a desarrollar.
También hay que recordar que por etiqueta de escritura, es necesario considerar que no todas las personas tienen el conocimiento necesario para entender la visón del tema técnico que se este explicando de manera escrita.
Por lo tanto es necesario utilizar un lenguaje simple para que el público que lea nuestro escrito pueda entenderlo y llevarlo a la práctica en su día a día.
“Te escribo una carta larga porque no tengo tiempo de escribir una corta”.
Una genialidad la frase de Blaise Pascal.
La frase matadora:
Recuerda que a veces escribimos mal porque pensamos mal.
Escribimos mal porque pensamos mal.
Alguien mas siente que los emojis que colocan en los títulos ayuda a “descansar” un poco?
Excelente, gracias
Muy buen capitulo 😃
Excelentes puntos.
Las palabras largas son más difíciles de entender por parte de nuestro cerebro.
Los aportes, preguntas y respuestas son vitales para aprender en comunidad. Regístrate o inicia sesión para participar.