En 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. 👐
Introducción al Technical Writing
¿Qué es Technical Writing? Lleva tu documentación al siguiente nivel
Habilidades para convertirte en Technical Writer
¿Conoces a tu público? Escribe específicamente para tu audiencia
Cómo entrevistar equipos de programación para recolectar información técnica
Estructura gramatical
Un repaso por la gramática básica
Voz activa vs. voz pasiva: estándares y estructura de una oración
Uso correcto de acrónimos y abreviaturas para explicar términos desconocidos
Técnicas de escritura fundamentales para documentos técnicos
Sigue las reglas de George Orwell para escribir con claridad
Uso correcto de listas y tablas para ordenar información
Tipos de párrafos y paso a paso para estructurarlos
Conceptos básicos de programación e ingeniería de software
¿Qué es programación? Evolución de la documentación y technical writing
Lenguajes de programación, tipos de datos y estructura de documentos HTML
Estándares de documentación de código
Cómo documentar una función de código
Buenas prácticas de legibilidad para código y comentarios
Organización y revisión de tu documentación
Organiza y define el alcance de tus documentos
Utiliza Markdown en documentos técnicos
Guía para revisar documentación en equipo de manera efectiva
Cómo organizar documentos largos
Diseño de documentos
Crea ilustraciones instructivas
Conclusiones
Siguientes pasos para convertirte en Technical Writer profesional
Lectura
¿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.
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:
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.
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:
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.
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 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”.
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
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. 🖼
Aportes 3
Preguntas 1
En 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. 👐
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.
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.
¿Quieres ver más aportes, preguntas y respuestas de la comunidad? Crea una cuenta o inicia sesión.