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:

• Elige escribir un solo documento grande o un conjunto de documentos.
• Organiza un documento.
• Añade navegación.
• Revela información de manera paulatina.

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:

• Laura es muy dispersa, para ella leer documentos largos es difícil y desorientador. Prefiere lo práctico, le gusta usar la herramienta de "búsqueda" en el sitio para encontrar respuestas rápidas a sus preguntas.
• A Eduardo le encanta leer y se siente a gusto navegando en documentos largos. A menudo utiliza la herramienta de "búsqueda" en su navegador para encontrar información útil.

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:

• Las guías de instrucciones, los resúmenes introductorios y las guías conceptuales suelen funcionar mejor como documentos más breves cuando se dirigen a lectores que son nuevos en el tema. Por ejemplo, un lector que es novato en el tema que estás explicando puede tener complicaciones para recordar bastantes términos y conceptos nuevos. Recuerda que tu público podría estar leyendo tu documentación para obtener una visión rápida y general del tema.
• Los tutoriales exhaustivos, las guías de mejores prácticas y documentos afines pueden funcionar bien como documentos más extensos, especialmente cuando están dirigidos a lectores que ya tienen alguna experiencia con las herramientas y el tema.
• Un gran tutorial puede basarse en una narración para guiar al lector a través de una serie de tareas relacionadas en un documento más largo. Sin embargo, esto puede ser cansado para el lector. En este punto puedes aplicar la máxima de "divide y vencerás", estos tutoriales pueden ser divididos en capítulos y hacer más amena su lectura.
• La mayoría de los documentos largos no están diseñados para ser leídos en una pasada. Normalmente, como lectores solemos escanear una página de referencia para buscar una explicación directa de lo que necesitamos saber.

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:

• Antes de pedirle al lector que realice una tarea, explícale por qué la hará. Por ejemplo, los siguientes puntos ilustran una sección de un esquema de un tutorial sobre cómo instalar un plugin en WordPress: -- Conocer cómo instalar un plugin directamente desde WordPress. El lector aprenderá cómo instalarlo de manera directa, manual o usando FTP. -- Enlistar los pasos para descargar un plugin e instalarlo.
• Limita cada paso de tu esquema a describir un concepto o completar una tarea específica.
• Estructura tu esquema de manera que tu documento presente la información más relevante para tu lector. No satures de información a tu lector de manera instantánea. Por ejemplo, es probable que el lector no necesite o no quiera saber la historia del proyecto en las secciones introductorias de tu documento cuando apenas está empezando con lo básico. Si crees que la historia del proyecto es útil, entonces agrégalo como documentación externa. Adjunta un enlace al final de tu documento que dirija a dicha información.
• Considera la posibilidad de explicar un concepto y luego demostrar cómo el lector puede aplicarlo. Los documentos que alternan entre la información conceptual y actividades prácticas son una forma atractiva de aprender.
• Antes de empezar a redactar, comparte el esquema con tus colaboradores. Los esquemas son especialmente útiles si trabajas con un equipo de colaboradores que van a revisar y poner a prueba tu documento.

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:

• El tema que trata el documento.
• Qué conocimientos previos, ya sea teóricos o técnicos, se espera que tengan los lectores.
• Lo que el documento no cubre.

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:

• Secciones de introducción y resumen.
• Desarrollo claro y lógico del tema.
• Títulos y subtítulos que ayudan a los usuarios a comprender el tema.
• Menú de índice que muestra a los usuarios dónde se encuentran en el documento.
• Enlaces a recursos relacionados o a información más detallada.

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:

• Habilitar depuración usando USB.
• Ejecutar Android Studio.

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

Curso de Introducción a SEO: Posicionamiento en Buscadores

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:

• En la medida de lo posible, agrega nueva terminología y conceptos.
• Introduce tablas, diagramas, listas y encabezados cuando sea apropiado.
• Reorganiza listas largas en listas cortas que expliquen cómo completar las subtareas.
• Empieza con ejemplos e instrucciones sencillas y añade paulatinamente técnicas más interesantes y complicadas. Por ejemplo, en un tutorial para el uso de un cliente de correo electrónico comienza explicando cómo personalizar su bandeja, cómo enviar correos electrónicos y luego introduce otras técnicas como organizar los mensajes por medio de etiquetas.

---

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. 🖼