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

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

7

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

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.

...

Reg铆strate o inicia sesi贸n para leer el resto del contenido.

Aportes 19

Preguntas 0

Ordenar por:

驴Quieres ver m谩s aportes, preguntas y respuestas de la comunidad?

o inicia sesi贸n.

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!

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:

隆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.

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 鈥淎unque鈥︹ en vez de 鈥淎 pesar de que鈥︹ es preferir frases cortas por la velocidad de lectura. En constraste, palabras superfluas ser铆an 鈥淏aja el menu hacia abajo鈥 o 鈥淵o mismo tuve que programarlo鈥. Usar palabras superfluas se suele considerar un vicio de lenguaje.

Esto tiene su excepci贸n: el uso intencionado del 茅nfasis. 鈥淵o 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:

  • Claridad: Escribir para que lo entiendan todos.
  • Concisi贸n: Usar solo las palabras indespensables, justas y significativas.
  • Densidad: Cada frase tiene sentido en el texto, o una idea por frase.
  • Exactitud: Evitar las palabras amplias de significado.
  • Precisi贸n: No divagar, ir directo a los hechos con rigurosidad.
  • Sencillez: Palabras de uso com煤n. Lo contrario es lo artificioso.
  • Brevedad: No escribir m谩s all谩 de lo indespensable y necesario.
  • Variedad: Evitar la monotom铆a. No repetir palabras frecuentemente.
  • Ritmo: En este caso, no usar un ritmo l铆rico ni filos贸fico.
  • Correcci贸n: El lenguaje debe ser correcto desde el punto de vista gramatical.

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.

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