Guía para revisar documentación en equipo de manera efectiva

En esta clase abarcaré consejos de edición que te ayudarán a convertir tu primer borrador en un documento que comunique de manera más clara la información que tu audiencia necesita. Utiliza un consejo o utilízalos todos; lo importante es encontrar una estrategia que funcione para ti y luego hacer que esa estrategia forme parte de tu rutina de escritura.

Autoedición ✌️

Imagina que acabas de escribir el primer borrador de un documento. ¿Cómo lo mejorarías? En la mayoría de casos, el trabajo hacia un documento final (publicado) es un proceso iterativo. Transformar una página en blanco en un primer borrador es a menudo el paso más difícil. Después de escribir un primer borrador asegúrate de reservar suficiente tiempo para perfeccionar tu documento.

La guía de los 12 pasos para escribir en internet

Adopta una guía de estilo 📚

Una guía de estilo es un conjunto de normas para la redacción y el diseño de contenidos; define el estilo que debe utilizarse en la comunicación dentro de una organización determinada. Las empresas, organizaciones y los grandes proyectos de código abierto suelen redactar o adoptar una guía de estilo existente para su documentación.

Para escribir la documentación de una manera más clara y mantener un tono, voz y estilo consistentes en tu documentación puedes leer y seguir una de estas guías de estilo:

• A List Apart
• Microsoft Style Guide
• University of Oxford Style Guide
• Google Developer Documentation Style Guide
• IBM Style Guide
• Airbnb JavaScript Style Guide

Algunas de estas pautas son puntos destacados que vimos en los módulos de “Introducción al Technical Writing” y “Estructura gramatical”. Puede que recuerdes algunas de las siguientes técnicas:

• Usar la voz activa para dejar claro quién está realizando la acción.
• Transcribir los pasos secuenciales en listas numeradas.
• Usar viñetas en la mayoría de las listas.

Los documentos con contenido efectivo presentan muchas otras técnicas que pueden ser útiles a la hora de escribir documentación técnica, por ejemplo:

• Escribir en segunda persona. Referirse a su audiencia como “tú” en lugar de “nosotros”.
• Poner circunstancias particulares antes de una instrucción, en lugar de después, como en los ejemplos de la siguiente imagen.

Otro caso de una circunstancia particular puesta antes de una instrucción es:

• Formatear el texto plano en formato de código.

Ejemplos:

- En HTML usa la etiqueta ``.
- En Markdown, usa comillas invertidas (```).

Piensa como tu audiencia 🧠

¿Quién es tu público? Retrocede, sal de la caja y trata de leer tu borrador desde el punto de vista de tus lectores. Asegúrate de que el objetivo de tu documento sea preciso y proporciona definiciones para cualquier término o concepto que pueda ser desconocido para tus lectores.

Puede ser útil hacer un “boceto” de una persona para tu público. Un personaje puede consistir en cualquiera de los siguientes atributos:

• Un rol como ingeniero de TI o un científico de datos.
• Un objetivo final, implementar un algoritmo de redes neuronales profundas.
• Un conjunto de suposiciones sobre el personaje y su conocimiento y experiencia. Por ejemplo, podrías asumir que tu personaje está:
  – Familiarizado con Python.
  – Corriendo un sistema operativo Linux.
  – Cómodo siguiendo las instrucciones de la línea de comandos.

Entonces puedes revisar tu borrador con tu personaje en mente. Puede ser especialmente útil contarle a tu audiencia cualquier suposición que hayas hecho. También puedes proporcionar enlaces a recursos donde puedan aprender más si necesitan repasar un tema específico.

Ten en cuenta que confiar demasiado en un personaje (o dos) puede dar lugar a un documento demasiado centrado para ser útil a la mayoría de tus lectores.

Para refrescar y obtener más información sobre este tema consulta la clase sobre cómo escribir específicamente para tu audiencia. 😉

Léelo en voz alta 📣

Dependiendo del contexto, el estilo de tu escritura puede enganchar, alienar o incluso aburrir a tu público. El estilo deseado de un documento determinado depende en cierta medida de la audiencia. Por ejemplo, la guía del colaborador de un nuevo proyecto de código abierto destinado a reclutar voluntarios podría adoptar un estilo más informal, mientras que la guía del desarrollador de una aplicación para una empresa comercial podría adoptar un estilo más formal.

Para comprobar que tu escritura es conversacional léela en voz alta. Escúchate y detecta si hay frases incómodas, oraciones demasiado largas o cualquier otra cosa que no parezca natural. También puedes intentar pedirle a otra persona que lea tu borrador en voz alta para ti, de esta manera te será más fácil detectar ajustes a realizar sobre tus escritos.

Vuelve a tu borrador más tarde 🔙

Después de que escribas tu primer borrador (o segundo o tercero), déjalo a un lado. Vuelve a él después de una hora (o dos o tres) y trata de leerlo con ojos frescos. Casi siempre notarás algo que podrías mejorar.

Cambia el contexto 🔁

A algunos escritores les gusta imprimir su documentación y revisar en una copia en papel y con lápiz rojo en la mano. Un cambio de contexto al revisar tu propio trabajo puede ayudarte a encontrar cosas para mejorar. Para una toma moderna de este consejo clásico, copia tu borrador en un documento diferente y cambia la fuente, el tamaño y el color.

Encuentra un editor colega 👥

Así como los ingenieros necesitan colegas para revisar su código, los escritores necesitan editores que les den retroalimentación sobre sus documentos. Pídele a alguien que revise tu documento y te dé una retroalimentación específica y constructiva. Tu editor colega no necesita ser un experto en el tema técnico de tu documento, pero sí necesita estar familiarizado con la guía de estilo que sigues.

Revisa tu documentación y entrégale un gran feedback a tus compañeros 🤝

Para completar esta clase también debes completar 2 nuevos desafíos:

1️⃣ Repasa todo lo que has aprendido en esta clase (y durante todo el curso), devuélvete a las clases anteriores de este módulo y entrégale feedback a los demás estudiantes que compartieron sus desafíos en la sección de comentarios.

2️⃣ Revisa una vez más la documentación de tus últimos retos. Aprovecha para agradecer por el feedback que te han dado tus compañeros y mejora tu documento. Y, por supuesto, compártenos en la sección de comentarios tu nueva documentación (y qué aspectos lograste mejorar gracias a esta nueva revisión).

Sé que entregar y recibir feedback no es nada fácil. De hecho, es una habilidad indispensable a la hora de trabajar en equipo profesionalmente. No te preocupes, lo harás muy bien. Te recomiendo tomar estas clases para asegurarte de hacerlo excelente.

• Cómo dar y recibir Feedback Efectivo
• Sé un buen líder dando feedback constructivo

---

Durante este módulo hemos comenzado a aprender a darle orden a nuestros documentos. En la siguiente clase profundizaremos en todo esto para darle forma a documentos largos. ¡Te veo allí!