Curso de Introducción al Technical Writing y Documentación de Código
Contenido del curso
Consejos de Autoedición para Mejorar Documentos Escritos
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.
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:
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:
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:
Otro caso de una circunstancia particular puesta antes de una instrucción es:
formato de código.Ejemplos:
- En HTML usa la etiqueta `<body>`. - 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:
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. :wink:
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:
:one: 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.
:two: 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.
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í!
Juan Castro
Profesor
H. Benjamín Muñoz
Estudiante
Luis Uriel Lugo Ramírez
Estudiante
JUAN MANUEL YOUNG HOYOS
Estudiante
Andrei Perez
Estudiante
Daniel Fernando Diaz Carvajal
EstudianteLas clases de edición con motosierra y herramientas quirúrjicas de edición del Curso de Escritura Online y todo el Curso de Edición Periodística nos pueden ayudar un montón con la revisión de nuestros textos.
Hola! No entendí esta parte, alguien me lo podría explicar. Gracias!: Otro caso de una circunstancia particular puesta antes de una instrucción es:
Formatear el texto plano en formato de código.
Ejemplos:
Se refiere a indentar, poner el codigo en su sitio, en caso de que el texto este mal acomodado, y con el uso de markdown darle el 'formato', como se muestra en la figura, en el encabezado de code: !Uso de code
En Markdown para "enmarcar el código" se usa las "comillas invertidas" (``). Hay 2 maneras de usarlas (o al menos que yo conozca):
acento grave inline.), 3 abajo () y en medio colocas el código, se vería algo así:print("Hello world")
Nota: Si en la parte de arriba en los 3 primeros acentos (```) le colocamos el nombre del lenguaje, este le pondrá los colores que resalten el lenguaje, un ejemplo:
Después de los 3 acentos le colocas el lenguaje ```python.
import os print("Hello world") def function_x(): pass
Pude mejorar la organización de la frase, ya que continuamente lo colocaba en voz pasiva
En este feedback sobre technical writing será enfocado en pasos que debes tener en cuenta para poder lograr una documentación precisa y acertada a tus lectores: