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

Guía para revisar documentación en equipo de manera efectiva

17/20

Lectura

En esta clase abarcaré consejos de edición que te ayudarán a convertir tu primer borrador en un documento que comunique de manera más clara la información que tu audiencia necesita. Utiliza un consejo o utilízalos todos; lo importante es encontrar una estrategia que funcione para ti y luego hacer que esa estrategia forme parte de tu rutina de escritura.

Autoedición ✌️

Imagina que acabas de escribir el primer borrador de un documento. ¿Cómo lo mejorarías? En la mayoría de casos, el trabajo hacia un documento final (publicado) es un proceso iterativo. Transformar una página en blanco en un primer borrador es a menudo el paso más difícil. Después de escribir un primer borrador asegúrate de reservar suficiente tiempo para perfeccionar tu documento.

La guía de los 12 pasos para escribir en internet

Adopta una guía de estilo 📚

Una guía de estilo es un conjunto de normas para la redacción y el diseño de contenidos; define el estilo que debe utilizarse en la comunicación dentro de una organización determinada. Las empresas, organizaciones y los grandes proyectos de código abierto suelen redactar o adoptar una guía de estilo existente para su documentación.

Para escribir la documentación de una manera más clara y mantener un tono, voz y estilo consistentes en tu documentación puedes leer y seguir una de estas guías de estilo:

Algunas de estas pautas son puntos destacados que vimos en los módulos de “Introducción al Technical Writing” y “Estructura gramatical”. Puede que recuerdes algunas de las siguientes técnicas:

  • Usar la voz activa para dejar claro quién está realizando la acción.
  • Transcribir los pasos secuenciales en listas numeradas.
  • Usar viñetas en la mayoría de las listas.

Los documentos con contenido efectivo presentan muchas otras técnicas que pueden ser útiles a la hora de escribir documentación técnica, por ejemplo:

  • Escribir en segunda persona. Referirse a su audiencia como “tú” en lugar de “nosotros”.
  • Poner circunstancias particulares antes de una instrucción, en lugar de después, como en los ejemplos de la siguiente imagen.
Buenas prácticas Technical Writing

Otro caso de una circunstancia particular puesta antes de una instrucción es:

  • Formatear el texto plano en formato de código.

Ejemplos:

- En HTML usa la etiqueta ``.
- En Markdown, usa comillas invertidas (```).

Piensa como tu audiencia 🧠

¿Quién es tu público? Retrocede, sal de la caja y trata de leer tu borrador desde el punto de vista de tus lectores. Asegúrate de que el objetivo de tu documento sea preciso y proporciona definiciones para cualquier término o concepto que pueda ser desconocido para tus lectores.

Puede ser útil hacer un “boceto” de una persona para tu público. Un personaje puede consistir en cualquiera de los siguientes atributos:

  • Un rol como ingeniero de TI o un científico de datos.
  • Un objetivo final, implementar un algoritmo de redes neuronales profundas.
  • Un conjunto de suposiciones sobre el personaje y su conocimiento y experiencia. Por ejemplo, podrías asumir que tu personaje está:
    – Familiarizado con Python.
    – Corriendo un sistema operativo Linux.
    – Cómodo siguiendo las instrucciones de la línea de comandos.

Entonces puedes revisar tu borrador con tu personaje en mente. Puede ser especialmente útil contarle a tu audiencia cualquier suposición que hayas hecho. También puedes proporcionar enlaces a recursos donde puedan aprender más si necesitan repasar un tema específico.

Ten en cuenta que confiar demasiado en un personaje (o dos) puede dar lugar a un documento demasiado centrado para ser útil a la mayoría de tus lectores.

Para refrescar y obtener más información sobre este tema consulta la clase sobre cómo escribir específicamente para tu audiencia. 😉

Léelo en voz alta 📣

Dependiendo del contexto, el estilo de tu escritura puede enganchar, alienar o incluso aburrir a tu público. El estilo deseado de un documento determinado depende en cierta medida de la audiencia. Por ejemplo, la guía del colaborador de un nuevo proyecto de código abierto destinado a reclutar voluntarios podría adoptar un estilo más informal, mientras que la guía del desarrollador de una aplicación para una empresa comercial podría adoptar un estilo más formal.

Para comprobar que tu escritura es conversacional léela en voz alta. Escúchate y detecta si hay frases incómodas, oraciones demasiado largas o cualquier otra cosa que no parezca natural. También puedes intentar pedirle a otra persona que lea tu borrador en voz alta para ti, de esta manera te será más fácil detectar ajustes a realizar sobre tus escritos.

Vuelve a tu borrador más tarde 🔙

Después de que escribas tu primer borrador (o segundo o tercero), déjalo a un lado. Vuelve a él después de una hora (o dos o tres) y trata de leerlo con ojos frescos. Casi siempre notarás algo que podrías mejorar.

Cambia el contexto 🔁

A algunos escritores les gusta imprimir su documentación y revisar en una copia en papel y con lápiz rojo en la mano. Un cambio de contexto al revisar tu propio trabajo puede ayudarte a encontrar cosas para mejorar. Para una toma moderna de este consejo clásico, copia tu borrador en un documento diferente y cambia la fuente, el tamaño y el color.

Encuentra un editor colega 👥

Así como los ingenieros necesitan colegas para revisar su código, los escritores necesitan editores que les den retroalimentación sobre sus documentos. Pídele a alguien que revise tu documento y te dé una retroalimentación específica y constructiva. Tu editor colega no necesita ser un experto en el tema técnico de tu documento, pero sí necesita estar familiarizado con la guía de estilo que sigues.

Revisa tu documentación y entrégale un gran feedback a tus compañeros 🤝

Para completar esta clase también debes completar 2 nuevos desafíos:

1️⃣ Repasa todo lo que has aprendido en esta clase (y durante todo el curso), devuélvete a las clases anteriores de este módulo y entrégale feedback a los demás estudiantes que compartieron sus desafíos en la sección de comentarios.

2️⃣ Revisa una vez más la documentación de tus últimos retos. Aprovecha para agradecer por el feedback que te han dado tus compañeros y mejora tu documento. Y, por supuesto, compártenos en la sección de comentarios tu nueva documentación (y qué aspectos lograste mejorar gracias a esta nueva revisión).

Sé que entregar y recibir feedback no es nada fácil. De hecho, es una habilidad indispensable a la hora de trabajar en equipo profesionalmente. No te preocupes, lo harás muy bien. Te recomiendo tomar estas clases para asegurarte de hacerlo excelente.


Durante este módulo hemos comenzado a aprender a darle orden a nuestros documentos. En la siguiente clase profundizaremos en todo esto para darle forma a documentos largos. ¡Te veo allí!

Aportes 3

Preguntas 1

Ordenar por:

¿Quieres ver más aportes, preguntas y respuestas de la comunidad? Crea una cuenta o inicia sesión.

Las clases de edición con motosierra y herramientas quirúrjicas de edición del Curso de Escritura Online y todo el Curso de Edición Periodística nos pueden ayudar un montón con la revisión de nuestros textos.

Pude mejorar la organización de la frase, ya que continuamente lo colocaba en voz pasiva

En este feedback sobre technical writing será enfocado en pasos que debes tener en cuenta para poder lograr una documentación precisa y acertada a tus lectores:

  1. Identifica cuando puedes usar una voz pasiva o activa
  2. Identifica siempre el publico al cual le vas a escribir
  3. Determina párrafos precisos especialmente en la idea principal en el inicio del documento.
  4. Siempre antes de escribir has un análisis del publico que te va a leer para estar en su mismo lenguaje y no tener comentarios que los hagan dudar de tu conocimiento.
  5. Y finalmente ten claro que al momento de leerte deben entender o aprender algo que no sabian.