Curso de Introducción al Technical Writing y Documentación de Código
Contenido del curso
Organización Efectiva de Documentos Técnicos Largos
¿Cómo se organiza una gran colección de información en un documento o en un sitio web de manera coherente? ¿Cómo se reorganiza un documento o sitio web desordenado en algo accesible y útil? Son preguntas a las que te enfrentarás una vez que comiences a desarrollar documentos técnicos largos. Pero no todo está perdido, los siguientes procedimientos pueden ayudarte:
Veamos más a fondo cada punto a continuación.
¿Cuándo escribir documentos largos? 🤔
Hay dos sugerencias para resolver esta pregunta. La primera es que puedes organizar una colección de información en documentos independientes más largos. O puedes organizar un conjunto de documentos interconectados más cortos. Este último suele publicarse normalmente en sitios web, en wikis o en formatos estructurados similares.
Recordemos que en la clase sobre cómo escribir específicamente para tu audiencia aprendimos que nuestra audiencia puede ser variada. Tendremos lectores que responderán positivamente a los documentos más largos y otros lectores que quizás no. Considera los siguientes perfiles de dos lectores imaginarios para los que estás escribiendo la documentación:
Entonces, ¿deberías organizar tu material en un solo documento o en un conjunto de documentos en un sitio web? Antes de tomar una decisión, considera los siguientes puntos:
Organizar un documento 📃
A continuación, te enseñaré algunas técnicas para planificar un documento más extenso, entre ellas la creación de un esquema y la redacción de una introducción. Después de completar el primer borrador de un documento, puedes revisarlo contra tu esquema e introducción para asegurarte de que no se ha perdido nada del enfoque original que pretendes abarcar.
Esbozar un documento ✍️
Empezar con un esquema puede ayudar a agrupar los temas de los que quieres escribir y determinar en dónde se necesitan más detalles. El esquema te ayuda a mover los temas antes de que te pongas a escribir.
Puede ser útil pensar en un esquema como la narrativa de tu documento. No existen lineamientos a seguir para escribir un esquema, pero las siguientes sugerencias te proporcionarán consejos prácticos que pueden ser útiles:
Escribe una introducción a tu documento 🥁
Si los lectores de tu documentación no encuentran relevancia en el tema, es probable que lo ignoren. Para establecer las reglas básicas para tus usuarios te recomiendo que proporciones una introducción que incluya la siguiente información:
Recuerda que quieres provocar que tu documentación sea fácil de enganchar, así que no intentes cubrir todo en la introducción.
El siguiente párrafo es un ejemplo de una guía para desarrolladores que quieren aprender a crear una app móvil en Android. En este párrafo de introducción muestra las recomendaciones antes mencionadas como una visión general:
Bienvenido a las guías para desarrolladores de Android. Los documentos que se indican en el área de navegación de la izquierda te enseñan a crear apps de Android utilizando API del marco de trabajo de Android y otras bibliotecas. Esta guía es para perfiles técnicos con conocimiento intermedio en el lenguaje de programación Java. Si eres nuevo en Android y quieres entrar en el mundo de la programación, empieza con el instructivo *Crea tu primera app*.
Después de completar el primer borrador, verifica que todo el documento tenga las expectativas que estableciste en la introducción. ¿Proyectas en tu introducción una visión general precisa de los temas que cubre tu documento? Si la respuesta es sí, es señal de que vamos bien, si es lo contrario, despeja un rato tu mente y vuelve a redactarla.
Añade navegación en tu documento 🚀
Cuando estás creando o editando un documento largo, probablemente tienes que añadir navegación. Puede sonar como una tarea larga, pero afortunadamente puedes hacerlo con solo algunos clics.
Proporcionar navegación y señalización a tus lectores asegura que puedan encontrar lo que buscan y la información que necesitan al alcance. La navegación clara incluye:
Los consejos de las siguientes secciones pueden ayudarte a planificar los encabezados de tu documentación.
Elige los encabezados basados en tareas 👩💻
Elige un nombre de encabezado que describa la tarea en la que está trabajando tu lector. Evita los encabezados que se basen en terminologías o herramientas desconocidas.
Por ejemplo, supongamos que estás documentando el proceso de ejecución de una app móvil en un dispositivo real. Para ejecutar la app el lector debe conectar el dispositivo a la computadora con un cable USB y habilitar la depuración. Posteriormente, ejecutar la app desde Android Studio. A primera vista podría parecer lógico añadir cualquiera de los siguientes encabezados a las instrucciones:
A menos que tus lectores ya tengan mucha experiencia con la terminología y los conceptos de este tema, estarían perfectos esos encabezados. Sin embargo, es preferible usar términos más familiares, por ejemplo, "Cómo ejecutar la app desde un dispositivo real".
Agrega una breve introducción bajo cada encabezado 📝
La mayoría de los lectores agradecen al menos una breve introducción bajo cada encabezado para proporcionar algún contexto. Evita poner un encabezado de nivel tres inmediatamente después de un encabezado de nivel dos. No lo hagas así:
## Cómo ejecutar una app ### Cómo ejecutar la app en un dispositivo real
Mejor hazlo así:
## Cómo ejecutar una app En la lección anterior, aprendiste a crear una app para Android que muestra el mensaje "Hello, World!". Ahora podrás ejecutar la app en un dispositivo real o en un emulador. ### Cómo ejecutar una app móvil
Revela información paulatinamente 🗣
El aprendizaje de nuevos conceptos, ideas y técnicas puede ser una experiencia gratificante para muchos lectores que se sienten cómodos leyendo la documentación a su propio ritmo. Sin embargo, enfrentarse a demasiados nuevos conceptos e instrucciones demasiado rápido puede ser abrumador. Es más probable que los lectores sean receptivos a documentos más largos que les revelen paulatinamente nueva información cuando la necesiten.
Las siguientes recomendaciones te ayudarán a implementar la información de una manera paulatina en tus documentos:
Ya aprendiste a estructurar tus documentos y organizarlos cuando son muy largos. Ahora continuaremos con el siguiente módulo, donde aprenderemos a agregar más elementos de diseño a nuestros documentos y así hacerlos aún más atractivos. 🖼
Juan Castro
Profesor
Juan Esteban Galvis
Estudiante
Lisseth Ariadne
Estudiante
Nestor Jesus Rodriguez Rodriguez
Estudiante
Andrei Perez
Estudiante
Andres Galvis
Estudiante
Erika Gabriela Villanueva Perez de Leon
Estudiante
Facundo Pérez Schneider
EstudianteEn el Curso de Arquitectura de la Información con Usaria estudiamos más a fondo todo sobre los flujos y buenas prácticas de navegación en general. :open_hands:
Para la navegación me gusta Notion 🖤 ya que puedo crear una lista de contenidos, así miro los encabezados y al dar click al que me interesa voy directamente. Y todo sin tener que crear los links cada uno a mano.
¡Me gusta encontrarme con fans de Notion! :D
Tengo planeado después de este curso complementar con Notion. He visto aportes de compañeros desde Notion y quedan ¡Súper! :sunglasses:
No entiendo esta recomendación "Reorganiza listas largas en listas cortas que expliquen cómo completar las subtareas." me podrían explicar en otras palabras por favor
Divide y vencerás! Descomponer grandes tareas en pequeñas fracciones que hagan más sencillo completar el trabajo.
Yo soy programador y me gusta usar Visual Studio Code para tomar notas ya que puedo ordenar el texto sin necesidad de copiar o pegar. Y al mismo tiempo ver el producto finale que voy escribiendo con la estructura de Markdow.
Es más probable que los lectores sean receptivos a documentos más largos que les revelen paulatinamente nueva información cuando la necesiten.
Mmm, yo personalmente noto que los libros que son éxito de ventas suelen tener capítulos cortos. Esto puede traducirse en que se puede retener mejor al lector si se tienen algunos documentos pequeños para que el lector sienta que está “completando” una lectura mientras más lee, que si tiene uno largo que debe ser leído de punta a punta para que el lector pueda considerar una lectura como “completada”.
