Curso de Introducción al Technical Writing y Documentación de Código
Contenido del curso
Técnicas para Crear Ilustraciones Instructivas Efectivas
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:
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:
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
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
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.
Captura de pantalla sin 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:
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 CDMX con trasfondo de las avenidas principales
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.
Juan Castro
Profesor
Erika Gabriela Villanueva Perez de Leon
Estudiante
Lisseth Ariadne
Estudiante
Carlos Eduardo Gomez García
Profesor
Daniel Andres Rojas Paredes
Estudiante
Espinoza Angie
Estudiante
Alfonso Neil Jiménez Casallas
Estudiante
Nestor Jesus Rodriguez Rodriguez
EstudianteNestor Jesus Rodriguez Rodriguez
EstudianteNo 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.
¡A mí tampoco se me había ocurrido y sí es buena idea!
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 :D
hHel pie de pagina cumple la misma funcion que el alt text? o el alt text debe ser mas descriptibo?, que tips puedo usar para hacer mis alt text o el pie de imagen mas descriptivos.o
Otra herramienta gratuita para hacer diagramas:
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á :sweat_smile:
