Listas y Tablas en Escritura Técnica: Tipos y Usos Efectivos

Clase 9 de 20 • Curso de Introducción al Technical Writing y Documentación de Código

Clase anteriorSiguiente clase

Las buenas listas y tablas pueden transformar el caos técnico en algo ordenado. Generalmente los lectores técnicos aman las listas. Por lo tanto, cuando escribas busca oportunidades para convertir la prosa en listas. ¡Aquí te voy a decir cómo!

Diferentes tipos de listas y sus usos 📜

Cuando escribimos documentos, independientemente de que sean técnicos o no, se debe tomar en cuenta que nuestros lectores NO siempre leerán todo nuestro contenido. Harán un escaneo rápido en nuestros documentos y buscarán los elementos de su interés.

Las listas y las tablas son útiles porque hacen hincapié en elementos de interés. Cuando vemos listas o tablas con elementos puntuales nuestra atención se enfoca en ello. Además de facilitar la lectura, también crean más espacio en blanco en nuestros documentos y extienden el texto para que las páginas no parezcan hojas estáticas repletas de letras.

¿Tu texto tiene ritmo? Curso de Escritura Online en Platzi

Cada tipo de lista tiene una función relevante dentro del technical writing. Estas nos ayudan a que los lectores logren comprender, memorizar y revisar los puntos clave del tema en cuestión, seguir una secuencia de acciones o instrucciones y, además, separa los largos tramos de texto y los separa en frases cortas, así como lo estudiamos en la clase de cómo escribir con claridad.

Sin embargo, a pesar de la diversidad de tipos de listas que existen, todas deben cumplir algunos lineamientos generales, los cuales mencionaré en el siguiente punto.

Lineamientos generales de las listas 📚

En contextos de technical writing, debes utilizar un estilo específico de listas, como el que te presento aquí:

  • Utiliza las listas para resaltar o enfatizar el texto o para enumerar elementos secuenciales.
  • Usa espaciado, indentación y puntuación en cada frase.
  • Haz que los elementos de la lista sean paralelos en la redacción.
  • Asegúrate de que cada elemento enlistado tenga que ver con el enfoque de la lista.
  • Utiliza una introducción para presentar los elementos de la lista y para indicar el significado o propósito de esta (y puntuar con dos puntos).
  • Evita el uso excesivo de listas; el uso de demasiadas listas destruye su eficacia.
  • Puedes aprovechar la función "estilos" o "formatos" de tu software para crear listas verticales en lugar de construirlas manualmente.

Elige el tipo de lista correcto 👍

Los siguientes tipos de listas dominan en la escritura técnica:

  • Listas con viñetas
  • Listas numeradas
  • Listas incrustadas o embebidas

Utiliza una lista con viñetas para los artículos no ordenados. Y utiliza una lista numerada para los artículos ordenados. En otras palabras:

  • Si reorganizas los artículos de una lista con viñetas, el significado de la lista no cambia.
  • Si reorganizas los artículos de una lista numerada, el significado de la lista cambia.

Por ejemplo, hemos hecho la siguiente lista con viñetas, la cual al reorganizar sus elementos no cambia el significado de la lista:

Javascript es un lenguaje poderoso, sus usos más importantes son los siguientes:

- Desarrollo de sitios web del lado del cliente (frontend, en el navegador).
- Desarrollo de todo tipo de aplicaciones gracias a la plataforma NodeJS.
- Desarrollo de aplicaciones para dispositivos móviles, híbridas o que compilan a nativo.

La siguiente lista, por el contrario, debe ser una lista numerada, ya que si cambiáramos el orden de sus elementos, también cambiaría el significado de la lista:

Configurar una cuenta de GitHub:

1. Vaya a https://github.com/join.
2. Escriba un nombre de usuario, su dirección de correo electrónico y una contraseña.
3. Elija Sign up for GitHub y siga las instrucciones.

Una lista embebida contiene varios elementos dentro de una frase. Por ejemplo, la siguiente frase contiene una lista embebida con siete elementos:

CodeDeploy puede implementar una variedad de contenidos de aplicación prácticamente ilimitada, entre las que se incluyen código, funciones AWS Lambda sin servidor, archivos de configuración y web, ejecutables, paquetes, scripts y archivos multimedia.

En términos generales, las listas embebidas son una forma inadecuada de presentar información técnica. Lo adecuado es transformar las listas embebidas en listas con viñetas o listas numeradas. Veamos cómo quedaría la frase embebida presentada en el párrafo anterior a manera de lista con viñetas:

CodeDeploy puede implementar una variedad de contenidos de aplicación prácticamente ilimitada, entre las que se incluyen:

- Código
- Funciones AWS Lambda sin servidor
- Archivos de configuración y web
- Ejecutables
- Paquetes
- Scripts
- Archivos multimedia

Inicia tus listas con un verbo imperativo 🤜

En la medida de lo posible, trata de iniciar tus listas con un verbo imperativo. Un verbo imperativo es un verbo que le indica a alguien que debe hacer algo. Por ejemplo: comprobar, revisar, editar o corregir son verbos que indican al lector lo que debe hacer. Observa cómo todos los elementos de la siguiente lista numerada inician con un verbo imperativo.

Para poder usar AWS CodeDeploy por primera vez debes completar los pasos de configuración:

1. Aprovisiona un usuario de IAM.
2. Instala o actualiza y, a continuación, configura la AWS CLI.
3. Crea un rol de servicio para CodeDeploy.
4. Crea un perfil de instancia de IAM para las instancias Amazon EC2.

Utiliza mayúsculas y puntuación adecuadamente 🔠

Si los elementos de las listas son frases, utiliza mayúsculas y puntuación, si no son frases, no las uses. Tomemos de ejemplo las listas presentadas en este capítulo:

Sin mayúsculas ni puntuación:

CodeDeploy puede implementar una variedad de contenidos de aplicación prácticamente ilimitada, entre las que se incluyen:

- código
- funciones AWS Lambda sin servidor

Con mayúsculas y puntuación:

Para poder usar AWS CodeDeploy por primera vez, debe completar los pasos de configuración:

1. Aprovisiona un usuario de IAM.
2. Instala o actualiza y, a continuación, configura la AWS CLI.

Crea tablas útiles 🗂

Las tablas son esas filas y columnas de números y palabras. En su forma más simple, se conforma de filas y columnas. En la parte superior de la tabla lleva un encabezado y en el borde izquierdo pueden figurar encabezados de fila. Mayormente se usan para datos numéricos, pero tampoco te cierres a eso, encontrarás situaciones en las que se te presenten varios conceptos que tengan mismas categorías de detalle y te verás en la necesidad de usar una tabla.

A continuación encuentras un ejemplo sobre una tabla que muestra palabras claves del lenguaje Java que también son usadas en C#. Como verás, cumple con las características de la estructura descrita en los párrafos anteriores.

TABLA 2.png

Estilo y formato 💅

Ten en cuenta algunas directrices específicas de estilo y de formato de las tablas:

  • En el texto que antecede a la tabla explica qué significa los datos dentro de ella. No dejes que tus lectores adivinen de qué se trata.
  • No abrumes a tus lectores con tablas inmensas de 15 columnas y 50 filas. Simplifica y no distorsiones los datos.
  • Si usas unidades de medida, no pongas la abreviatura o la palabra completa en cada celda. Pon la abreviatura entre paréntesis en el encabezado de la columna o de la fila.
  • Si tus datos son números, alinéalos a la derecha.
  • Si tus datos son palabras, alinéalas a la izquierda o al centro.
  • Los encabezados de las columnas se centran en las columnas de datos numéricos y se alinean a la izquierda o al centro con las columnas de texto.

Las listas y las tablas son las mejores amigas tanto del technical writer como del lector. Ahora que sabes usarlas correctamente, utilízalas a tu favor.

¿Aprendiste a usar las listas a tu favor? 😎

Convierte el siguiente párrafo en una lista numerada:

Para cambiar la configuración regional en el emulador mediante el shell adb, elige la configuración regional que quieres probar y determina la etiqueta de idioma BCP-47; por ejemplo, el francés canadiense sería fr-CA. Después inicia un emulador y desde un shell de línea de comandos en la computadora host, ejecuta el siguiente comando:adb shell o si tienes un dispositivo adjunto, agrega la opción -e: adb -e shell para especificar que quieres el emulador. Finalmente, en el mensaje de shell adb (#), ejecuta este comando:setprop persist.sys.locale [*BCP-47 language tag*];stop;sleep 5;start.

¡Espero ver tu solución a este reto en los comentarios! En la próxima clase vamos a aprender paso a paso cómo se debe escribir un buen párrafo.