Introducci贸n al Technical Writing

1

驴Qu茅 es Technical Writing? Lleva tu documentaci贸n al siguiente nivel

2

Habilidades para convertirte en Technical Writer

3

驴Conoces a tu p煤blico? Escribe espec铆ficamente para tu audiencia

4

C贸mo entrevistar equipos de programaci贸n para recolectar informaci贸n t茅cnica

Estructura gramatical

5

Un repaso por la gram谩tica b谩sica

6

Voz activa vs. voz pasiva: est谩ndares y estructura de una oraci贸n

7

Uso correcto de acr贸nimos y abreviaturas para explicar t茅rminos desconocidos

T茅cnicas de escritura fundamentales para documentos t茅cnicos

8

Sigue las reglas de George Orwell para escribir con claridad

9

Uso correcto de listas y tablas para ordenar informaci贸n

10

Tipos de p谩rrafos y paso a paso para estructurarlos

Conceptos b谩sicos de programaci贸n e ingenier铆a de software

11

驴Qu茅 es programaci贸n? Evoluci贸n de la documentaci贸n y technical writing

12

Lenguajes de programaci贸n, tipos de datos y estructura de documentos HTML

Est谩ndares de documentaci贸n de c贸digo

13

C贸mo documentar una funci贸n de c贸digo

14

Buenas pr谩cticas de legibilidad para c贸digo y comentarios

Organizaci贸n y revisi贸n de tu documentaci贸n

15

Organiza y define el alcance de tus documentos

16

Utiliza Markdown en documentos t茅cnicos

17

Gu铆a para revisar documentaci贸n en equipo de manera efectiva

18

C贸mo organizar documentos largos

Dise帽o de documentos

19

Crea ilustraciones instructivas

Conclusiones

20

Siguientes pasos para convertirte en Technical Writer profesional

Sigue las reglas de George Orwell para escribir con claridad

8/20

Lectura

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:

鈥淭e 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.

C贸mo escribir bien para internet

Aqu铆 te muestro un ejemplo de una frase muy larga con m煤ltiples conceptos:

鈥淓l 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 鈥揗inix鈥 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:

鈥淓l 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 鈥揗inix鈥 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 鈥渉ay鈥 馃檯鈥嶁檧锔

No aburras a tus lectores usando la palabra 鈥渉ay鈥. 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 鈥渃omida 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 鈥渓ista鈥, 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:

Los aportes, preguntas y respuestas son vitales para aprender en comunidad. Reg铆strate o inicia sesi贸n para participar.

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:

Las reglas de George Orwell me recordaron al 鈥淶en 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.

鈥淭e 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 鈥渄escansar鈥 un poco?

Excelente, gracias

Muy buen capitulo 馃槂

Excelentes puntos.

Las palabras largas son m谩s dif铆ciles de entender por parte de nuestro cerebro.