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

Uso correcto de acrónimos y abreviaturas para explicar términos desconocidos

7/20

Lectura

Un tema particular del technical writing cuando escribimos documentos es utilizar de manera frecuente terminología desconocida para algunos o la mayoría de los lectores. Esta terminología es importante ubicarla y definirla. Las siguientes tácticas te ayudarán con esto.

Explica términos nuevos o desconocidos 😅

Conforme vas forjando tus habilidades de escritura aprenderás que algunos términos pueden ser desconocidos para algunos o todos tus lectores. Incluso encontrarás términos desconocidos para ti. Es por ello que nuestro deber es comprender dichos términos y ligarlos a explicaciones, comparaciones o ejemplos para que nuestros lectores tengan una referencia más tangible.

Si tu documento gira en torno a ese término desconocido, define desde un principio su significado. Pero si tu documento tiene muchos términos desconocidos, lo más recomendable es que hagas un glosario con todas las definiciones.

Usa términos de forma coherente 🙏

Supongamos que escribiste algunas líneas de código y a una variable llamada nombre le cambias el nombre por name a la mitad de la ejecución de un método. Es evidente que tu código no compilará. Eso mismo pasa cuando escribes un documento y usas un término de manera frecuente, si a mitad del documento lo cambias, el hilo de tu texto se perderá y las ideas en las cabezas de tus lectores no “compilarán”.

Para evitarlo utiliza el mismo término que has usado a lo largo de tu documento. Una vez que ya estás usando un término a lo largo de tu escritura, no lo modifiques ni lo renombres.

Usa abreviaturas 💕

Existen casos en los que algunos conceptos se pueden usar de manera abreviada y luego puedes usar esa abreviatura durante todo el documento.

“La tecnología educativa, es decir, la EdTech, se ha convertido en la herramienta que enriquece el proceso de enseñanza de niños y adultos. La EdTech orientada a niños y adolescentes busca que estos aprendan de una forma más sencilla a través de la personalización de su educación”.

Wireless Fidelity (WiFi): este término fue creado por una empresa de branding y solo se hizo popular en su forma abreviada. Al igual que los transistores de radio tradicionales, las redes WiFi transmiten información por el aire utilizando ondas de radio”.

Usa acrónimos adecuadamente 🤏

El uso de acrónimos es algo común en cualquier escrito técnico. El acrónimo tiene cierta similitud con las siglas, la única diferencia es que un acrónimo puede formarse tomando tanto la inicial como la primera parte de las palabras que forman el nombre completo, en cambio, la sigla siempre se forma con la letra inicial.

Si usas un acrónimo desconocido en tu documento, lo ideal es que escribas el término completo y después el acrónimo entre paréntesis, ejemplo:

Hypertext Transfer Protocol Secure (HTTPS) es un protocolo de comunicación de internet que protege la integridad y la confidencialidad de los datos de los usuarios entre sus ordenadores y el sitio web. Te recomendamos que adoptes HTTPS para proteger sus conexiones con tu sitio web, independientemente de lo que este contenga".

Los datos que se envían mediante HTTPS están protegidos con el protocolo Seguridad en la capa de transporte (TLS).

Si defines el significado completo del acrónimo en su primera mención, es suficiente. Ya sobre el texto puedes usarlo y el lector se irá familiarizando con el acrónimo. Aunque pasa algo curioso con los acrónimos, ya que sobre la marcha van generando una identidad, tanto así que llega el momento en que nuestros lectores solo recuerdan el acrónimo en sí, pero no su significado tal cual. Ejemplos actuales de esto son: “www”, “HTML”, “SaaS”, “HTTPS”, entre otros.

Las sugerencias puntuales para el uso de acrónimos son:

  • Si el acrónimo será usado pocas veces, no es necesario definirlo.
  • Si el acrónimo es más corto que el término completo y lo vas a usar muchas veces en el documento, sí es necesario definirlo.

Como verás, algunos términos quizá sean muy familiares para nosotros, pero habrá personas que ni sabían de la existencia de estas palabras. Así que enfócate siempre en quienes te leerán y trata de ser lo más claro posible en cada uno de tus documentos técnicos sin caer en palabras rimbombantes o en palabras que parecen sacadas de otro planeta.


¡Te espero en la próxima clase! Estudiaremos diferentes tipos de voz y cuándo usar voz pasiva o activa.

Aportes 9

Preguntas 0

Ordenar por:

¿Quieres ver más aportes, preguntas y respuestas de la comunidad? Crea una cuenta o inicia sesión.

Creo que el mejor ejemplo de esto es Wikipedia, dado que define al inicio los acrónimos o abreviaturas, y a cada termino desconocido lo enlaza con su definición (Así si no conoce el termino pues puede consultarlo). Y al final deja una sección llamada: “Notas y referencias” y “Enlaces externos” para complementar la lectura.

Me hubiera gustado que también pusieran reto en esta sección, ya que me ayudan a reforzar lo aprendido.

  • Explicación de términos nuevos o que la mayoría desconoce, y ponerlos en un glosario
  • Usar términos coherentes y ocupar los mismos en la documentación
  • Si usas abreviaturas primero escribir el nombre completo y después su abreviación para que el lector entienda que de ahora en adelante aparecerá abreviado
  • Similar a los acrónimos, primero escribir el nombre completo seguido de el acrónimo en paréntesis, para poder ocupar el acrónimo mas adelante.

En un curso que tome de Oratoria nos mencionaban que es mejor hablar y escribir en positivo así generamos armonía y tranquilidad al leer. Ejemplo:

Negativo: A continuación veremos los problemas mas comunes dentro del proyecto. -> Solo resaltas que hay problemas.
Positivo: A continuación veremos los puntos de mejora mas comunes dentro del proyecto. -> Invitas a dar una solución.

📌 Los tres párrafos que más me llamaron la atención:
.
Supongamos que escribiste algunas líneas de código y a una variable llamada nombre le cambias el nombre por name a la mitad de la ejecución de un método. Es evidente que tu código no compilará. Eso mismo pasa cuando escribes un documento y usas un término de manera frecuente, si a mitad del documento lo cambias, el hilo de tu texto se perderá y las ideas en las cabezas de tus lectores no “compilarán”.
.
El acrónimo tiene cierta similitud con las siglas, la única diferencia es que un acrónimo puede formarse tomando tanto la inicial como la primera parte de las palabras que forman el nombre completo, en cambio, la sigla siempre se forma con la letra inicial.
.
Wireless Fidelity (WiFi): este término fue creado por una empresa de branding y solo se hizo popular en su forma abreviada.

Me llamo la atención lo del WIFI y las ondas de radio lo busque(wikipedia) y los tres primeros textos los hice medio. 🐰😎
https://bit.ly/3hFY3ED
Pueden ser creadas de manera natural por fenómenos naturales tales como relámpagos, o por objetos astronómicos. También pueden ser generadas de manera artificial como en radares ó redes telemáticas. Sí las ondas de radio que son un tipo de radiación electromagnética. Como todas las ondas electromagnéticas si viajan por el vacio las ondas de radio viaja a la velocidad de la luz y su propagación se mide en frecuencias de 10THz hasta 10kHz.

Acrónimo

  • OPEP: Organización, petróleo, país exportador
  • RRHH: Recursos Humanos
  • DND: No molestar
  • ASAP: Tan pronto como sea posible
  • DIY: hágalo usted mismo
  • PIN: Número de identificación personal
  • FBI: Oficina Federal de Investigaciones
  • NASA: Administración Nacional de Aeronáutica y del Espacio
  • SIDA: síndrome de inmunodeficiencia adquirida.
  • FYI: para su información
  • ATM: cajero automático
  • OVNI: Objeto volador no identificado
  • VIH: virus de la inmunodeficiencia humana
  • IQ: Cociente de inteligencia
  • SOS: Salva nuestras almas

Abreviatura

  • Km: Kilómetro
  • Dpto: Departamento
  • Eng: Inglaterra, inglés
  • Col: Coronel
  • Geog: Geografía
  • Lit: Literario, Literatura
  • Ref: Referencia
  • Rept: Informe
  • Viz: Videlicet
  • Año: año
  • St: Santo
  • Asunto : Asunto
  • Univ: Universidad
  • Vocabulario: vocabulario.

Fuente

Yo solía hacer las cosas al revés de como lo explica esta lectura. Colocaba el acrónimo al inicio y entre paréntesis colocaba su definición larga.

HTTPS (Hypertext Transfer Protocol Secure)…

Es muy útil haber encontrado esta lectura para saber que lo que estaba haciendo estaba mal, ya sé que debo arreglarlo para el futuro.

Esta acción de definir se puede ver en todas las documentaciones oficiales de reconocidos softwares. Creo que también agregaría el hecho de que se agregue un índice y una sección donde se hablen exclusivamente de los tecnicismos que pueden resultar mas complicados de comprender.

Que bueno seria que para estas clases de lectura se pueda mover el panel de comentarios o hacer la vista más grande

Excelente el contenido del curso