Introducci贸n al Technical Writing

1

驴Qu茅 es Technical Writing? Lleva tu documentaci贸n al siguiente nivel

2

Habilidades para convertirte en Technical Writer

3

驴Conoces a tu p煤blico? Escribe espec铆ficamente para tu audiencia

4

C贸mo entrevistar equipos de programaci贸n para recolectar informaci贸n t茅cnica

Estructura gramatical

5

Un repaso por la gram谩tica b谩sica

6

Voz activa vs. voz pasiva: est谩ndares y estructura de una oraci贸n

7

Uso correcto de acr贸nimos y abreviaturas para explicar t茅rminos desconocidos

T茅cnicas de escritura fundamentales para documentos t茅cnicos

8

Sigue las reglas de George Orwell para escribir con claridad

9

Uso correcto de listas y tablas para ordenar informaci贸n

10

Tipos de p谩rrafos y paso a paso para estructurarlos

Conceptos b谩sicos de programaci贸n e ingenier铆a de software

11

驴Qu茅 es programaci贸n? Evoluci贸n de la documentaci贸n y technical writing

12

Lenguajes de programaci贸n, tipos de datos y estructura de documentos HTML

Est谩ndares de documentaci贸n de c贸digo

13

C贸mo documentar una funci贸n de c贸digo

14

Buenas pr谩cticas de legibilidad para c贸digo y comentarios

Organizaci贸n y revisi贸n de tu documentaci贸n

15

Organiza y define el alcance de tus documentos

16

Utiliza Markdown en documentos t茅cnicos

17

Gu铆a para revisar documentaci贸n en equipo de manera efectiva

18

C贸mo organizar documentos largos

Dise帽o de documentos

19

Crea ilustraciones instructivas

Conclusiones

20

Siguientes pasos para convertirte en Technical Writer profesional

C贸mo organizar documentos largos

18/20

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:

  • 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 鈥渂煤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 鈥渂煤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. 馃柤

Aportes 3

Preguntas 1

Ordenar por:

驴Quieres ver m谩s aportes, preguntas y respuestas de la comunidad? Crea una cuenta o inicia sesi贸n.

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.