Curso de Introducción al Technical Writing y Documentación de Código
Contenido del curso
Escritura Técnica Clara y Efectiva
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á!
Mario Andrés Castro Martínez
Estudiante
Raul Santos
Estudiante
Juan Castro
Profesor
Gonzalo Gramaglia
Estudiante
Nestor Jesus Rodriguez Rodriguez
Estudiante
Cristian Blandon
Estudiante
Fernando Campos
EstudianteGonzalo Gramaglia
Estudiante
Maided Guadalupe Hernández Ponce
Estudiante
David Furniel
Estudiante
Jose Luis Bedoya
Estudiante
Daniel Andres Rojas Paredes
Estudiante
Oscar Israel Román Quispe
Estudiante
Pedro Carreño
Estudiante
Hipólito Morales
Estudiante
Jorge Rosales
Estudiante
Rubén Cuello
Estudiante
Lisseth Ariadne
Estudiante
Donna Eunice Lima Ac
Estudiante
Reinaldo Mendoza
EstudianteArredondo Escoto Jose Antonio
Estudiante
Elmer Padilla Espinoza
Estudiante
Alejandro Maldonado A.
EstudianteLas 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!
De heco casi todo el zen de Python cumple con todo lo que henos visto hasta ahora, por eso Python es genial.
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:
Gracias por el aporte Juan!! 💯👌
Llegué a Platzi por programación, pero este tipo de clases me muestran las falencias que tengo con respecto a mis habilidades blandas, so, let's go for it! :runner:
¡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! :D
¿Cómo sabes si un verbo es fuerte o débil?
📌 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.
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.
me parece un acercamiento importante que este curso empiece con recomendaciones sobre como escribir mejor!
in oder words...K.S.S (keep it short and simple) bb
Muy interesante.
Me gustaría precisar que en el apartado de palabras superfluas, una cosa es la concisión y otra es usar palabras superfluas. El caso de "Aunque..." en vez de "A pesar de que..." es preferir frases cortas por la velocidad de lectura. En constraste, palabras superfluas serían "Baja el menu ++hacia abajo++" o "Yo ++mismo++ tuve que programarlo". Usar palabras superfluas se suele considerar un vicio de lenguaje.
Esto tiene su excepción: el uso intencionado del énfasis. "Yo mismo tuve que programarlo" tiene diferente significado si lo escribe el gerente de TI de una gran empresa que si lo escribe un technical writer.
Asimismo, si como redactor técnico tienes que trabajar con abogados (por ejemplo, para temas legales de informática), deberás acostumbrarte a leer documentos y materiales con escritura compleja. Algo similar pasa cuando se trabaja con académicos. De ahí se desprende que tienes que ser capaz de leer y entender textos complejos.
Estas son algunas sutilezas del lenguaje que es necesario conocer para mejorar nuestros skills como technical writers.
Otro aporte es que veo muchas similitudes con la redacción periodística. Algunos de sus principios son:
Me parece que si tantas personas tienen problemas en ser cortos y concisos a la hora de escribir creo que en gran parte es culpa de la escuela y la educación tradicional. Por situaciones como "redactar informe de tema [tema] de mínimo 4 paginas" cuando debería priorizarse la calidad del contenido en vez de la extension del mismo.
Faltaron dos reglas de Orwell en caso de que a alguien le interese:
Nunca uses una metáfora, símil u otra figura retórica que estás acostumbrado a ver impresa.
Rompe cualquiera de estas reglas antes de que te hagan decir una auténtica barbaridad
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.
