Organización y Creación de Documentos Técnicos Coherentes
Clase 15 de 20 • Curso de Introducción al Technical Writing y Documentación de Código
Contenido del curso
Ya sabes escribir frases coherentes, puedes escribir párrafos claros y precisos. Ahora vamos a aprender a organizar todos esos párrafos en un documento coherente. Así que... here we go!
Define el alcance de tu documento 📏
Un buen documento comienza por definir su alcance. Por ejemplo:
Este documento describe cómo crear apps para Android utilizando la API del marco de trabajo de Android y otras bibliotecas de código abierto.
Estas definiciones de alcance benefician tanto al lector como al technical writer. Puede suceder que, mientras escribes, el contenido de tu documento se aleje de la definición del alcance. Lo que debes de hacer es reenfocar el documento al alcance definido o modificar la definición del alcance.
De cualquier manera, al revisar tu primer borrador puedes eliminar (o pasar a otro documento) cualquier sección que no ayude a satisfacer el alcance del documento.
Define a tu audiencia 👩👩👧👦
Un buen documento especifica explícitamente su audiencia y cualquier conocimiento o experiencia previa. Por ejemplo:
Esta documentación está dirigida para los desarrolladores familiarizados con la programación en JavaScript y conocimientos de programación orientada a objetos.
Establece los puntos clave por adelantado ✊
Nuestros lectores son personas ocupadas que no necesariamente leerán todas las páginas de nuestro documento. Imagina que solo pueden leer el primer párrafo de la página uno. Al revisar tu documentación asegúrate de que el inicio de tu documento responda a las preguntas esenciales de tus lectores.
Los escritores profesionales concentran una energía considerable en la página uno para aumentar las probabilidades de que los lectores lleguen a la página dos. Sin embargo, la página uno de cualquier documento largo es la más difícil de escribir. Prepárate para revisar la página uno muchas veces.
Siempre escribe un resumen ejecutivo (también conocido como abstract) para los documentos largos. Aunque el resumen ejecutivo debe ser muy corto, toma en cuenta que pasarás mucho tiempo escribiéndolo. Un resumen ejecutivo aburrido o confuso es una señal que advierte a los potenciales lectores de que se mantengan alejados.
Cómo escribir para tu audiencia 🚀
A lo largo de este curso he enfatizado varias veces la importancia de definir tu audiencia. En esta sección nos centramos en la definición de la audiencia como un medio para organizar tu documento.
Preguntas para definir a tu audiencia ❓
Responder a las siguientes preguntas te ayudará a determinar qué debe contener tu documento:
Por ejemplo, supongamos que en una organización implementarán un nuevo algoritmo de redes neuronales profundas en un programa. La siguiente lista contiene algunas respuestas potenciales a las preguntas anteriores:
Cómo organizar la estructura de tu documento 🏗
Después de definir tu público, organiza el documento para proporcionar lo que los lectores deben saber o ser capaces de hacer después de leer el documento. Por ejemplo, el esquema del documento podría ser el siguiente:
Además, ten en cuenta la segmentación de tu público para darle un enfoque correcto a tu documento. Por ejemplo, el público objetivo estudió Python, pero aproximadamente una cuarta parte de tu público podría no recordar los detalles de la API de Keras. Por lo tanto, es probable que en el documento insertes referencias a documentación externa de la API en lugar de intentar explicarla.
Documentación modular: divide tu tema en secciones 🔪
La programación modular se divide en archivos, clases y métodos. El código modular es más fácil de leer, entender, mantener y reutilizar. Hacer que nuestros documentos sean modulares nos da los mismos beneficios. Si eres programador, probablemente tengas una fuerte familiarización con la modularidad funcional en el código, pero ¿cómo usarías estos principios en tu escritura?
Imagina que tienes una bodega vacía en la que necesitas guardar un lote de cajas grandes, medianas y pequeñas. ¿Cómo planearías meter las cajas para asegurarte de que todas podrán entrar en la bodega? Por supuesto que primero meterías las cajas grandes, luego las medianas y finalmente las pequeñas. Si intentaras hacer esto en el orden contrario, fallarás.
La cabeza del lector se parece mucho a una bodega vacía. La información generalmente se acomoda en su cerebro en tres tamaños: grande, mediana y pequeña. Los tamaños de la caja son el tamaño de la información. Necesitas acomodar cada caja dentro del espacio de la cabeza de nuestro lector para que procese y entienda nuestros escritos.
Para decidir el orden de esta información y saber el orden en que debemos de escribirla puedes usar la estrategia de grabarte a ti mismo hablando (o escribiendo libremente) sobre algún tema durante un corto período de tiempo, pueden ser 2 a 5 minutos. Sé específico en tu explicación. Inténtalo varias veces hasta que seas capaz de entenderte a ti mismo y te parezca coherente.
Lo sé, esto requiere disciplina, pero es una herramienta infalible para comunicar la información de manera modular.
¿Pondrás en práctica estos ejercicios? 🔥
Antes de avanzar a la siguiente clase debes completar los siguientes 2 desafíos.
:one: Escribe una documentación para principiantes sobre cómo conectar un celular vía USB a tu computadora.
:two: Escribe la documentación de un programa o función que hayas escrito por tu propia cuenta (en cualquier lenguaje de programación). Imagina que quieres convertir tu proyecto en open-source y estás escribiendo esta documentación para que otras programadoras entiendan tu programa y puedan ayudarte a escalarlo.
Recuerda poner en práctica lo que aprendiste en esta clase. Debes definir el alcance, audiencia y puntos clave de tus documentos.
¡Cuéntame en la sección de comentarios cómo te fue! En la siguiente clase aprenderemos cómo utilizar Markdown para escribir nuestra documentación. ✍