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

Crea ilustraciones instructivas

19/20

Lectura

El uso de ilustraciones instructivas es una fase fundamental durante la elaboraci贸n de la documentaci贸n t茅cnica. Las ilustraciones ayudan a transmitir a tus lectores informaci贸n compleja de una manera m谩s comprensible y clara. Un caso recurrente que sucede cuando se trata de leer material t茅cnico es que los lectores prefieren ver ilustraciones en lugar de texto. Estas se utilizan para informar, explicar, ilustrar o aprender. Y pueden ser im谩genes, dise帽os, gr谩ficos instructivos, entre otros.

En este clase aprender谩s algunas t茅cnicas y recursos de ayuda para crear ilustraciones instructivas que ayuden a que tus lectores logren comprender la informaci贸n expuesta en tus documentos de una manera m谩s sencilla. Como dice el proverbio chino: "una imagen vale m谩s que mil palabras".

Enfoca tu ilustraci贸n en el pie de imagen 馃懇鈥嶐煄

En ocasiones ser谩 complicado elegir la ilustraci贸n ideal para mostrar a tus lectores. Te sugiero que comiences por escribir primero el pie de imagen (o pie de foto/ilustraci贸n鈥) y a partir de eso tendr谩s m谩s enfoque en lo que debe de incluir tu ilustraci贸n. El pie de imagen es el breve texto descriptivo que aparece al borde inferior de la ilustraci贸n y tiene como objetivo darle un sentido concreto a lo que se muestra.

Las caracter铆sticas de un buen pie de imagen son las siguientes:

  • Es breve y conciso.
  • Aporta informaci贸n necesaria.
  • Debe atraer la atenci贸n de tu lector.

El siguiente pie de imagen es un ejemplo del libro 鈥Blockchain for Dummies鈥 de IBM. Como observar谩s, la descripci贸n del pie de imagen tiene que ver con lo que se muestra en la ilustraci贸n:

pie de imagen - blockchain for dummies - IBM

Imagen del libro Blockchain for Dummies

Evita ilustraciones t茅cnicas complejas 馃毇

As铆 como la sugerencia de escribir pies de im谩genes breves y concisos, lo mismo pasa con el contenido de las ilustraciones que vayas a usar. Deben de ser simples y legibles a la vista. Los technical writers de Google recomiendan evitar las ilustraciones que requieren m谩s de cinco puntos para explicarse. Por ejemplo, este tipo de ilustraciones podr铆an llegar a confundir a tus lectores:

ilustraciones complejas

Ilustraciones complejas

En estos casos, la sugerencia que los expertos dan es que se divida en m贸dulos para que la ilustraci贸n sea visualmente digerible. La siguiente ilustraci贸n, por ejemplo, pasa de ser un sistema complejo a un sistema dividido en tres m贸dulos:

Ilustraci贸n dividida en m贸dulos

Ilustraci贸n dividida en m贸dulos

Usa se帽ales visuales 馃憖

Cuando realices capturas de pantallas (screenshots) con varios elementos utiliza figuras para se帽alar el punto a observar. Puedes usar un rect谩ngulo, un 贸valo, una flecha o cualquier figura que enfoque la atenci贸n de tu lector para que no se pierda en la imagen.

Notion: captura de pantalla sin se帽al visual

Captura de pantalla sin se帽al visual

Notion: Captura de pantalla con se帽al visual

Captura de pantalla con se帽al visual

Simplifica tus ilustraciones 馃彸

驴Recuerdas que cuando escribimos nuestros primeros documentos tenemos que hacerlos a manera de borradores y sobre la marcha irlos mejorando? Es lo mismo con las ilustraciones. Podemos modificar las ya existentes y, por supuesto, irlas mejorando.

Cuando hagas la revisi贸n de tus ilustraciones, toma en cuenta los siguientes puntos:

  • Hacer lo m谩s simple posible la ilustraci贸n.
  • Dividir en m贸dulos la ilustraci贸n en caso de que sea compleja a la vista.
  • Revisar que los colores y las fuentes sean adecuadas para su lectura.

Un ejemplo sencillo podr铆a ser este mapa del metro de la CDMX. Imaginemos que el punto principal es mostrar las rutas del metro. Evidentemente, el segundo ejemplo es m谩s legible que el primero.

Metro de la Ciudad de M茅xico

Metro de la CDMX con trasfondo de las avenidas principales

Metro de la Ciudad de M茅xico

Metro de la CDMX sin trasfondo de las avenidas principales

Herramientas gratuitas 猸

Te comparto una peque帽a lista de herramientas gratuitas de diagramado que puedes encontrar en la web, son gratuitas y muy intuitivas:

Nunca pierdas de vista el objetivo de tus documentos t茅cnicos ni las necesidades de tus lectores. Mientras construyes tus documentos ten siempre en mente a tu audiencia. De esta manera, con la pr谩ctica y experiencia que obtengas a lo largo de tu trayectoria lograr谩s crear una documentaci贸n t茅cnica eficiente y sencilla.

Convi茅rtete en el superh茅roe que los lectores t茅cnicos necesitan.

Aportes 6

Preguntas 0

Ordenar por:

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

No se me hab铆a ocurrido empezar por escribir el pie de pagina y despu茅s la imagen, considero que ser谩 muy practico.
Tambi茅n generar im谩genes sin mucha complejidad, poniendo solo lo m铆nimo necesario para que sean entendibles.

Aunque parezca incre铆ble, yo prefiero la primera imagen del metro sobre la segunda jajaja, pero en mi caso usar铆a un tono de gris m谩s claro para las avenidas 馃槃

para quienes estamos interesados en documentar gr谩ficos en Data Analytics, es recomendable tomar este curso en Platzi

Se parece mucho al sistema de Trasnmilenio de Bogot谩

jajaja por un momento pens茅 que era el sistema de Transmilenio de Bogot谩 馃槄