Curso de Introducción al Technical Writing y Documentación de Código
Contenido del curso
Escritura Técnica: Definición y Uso de Términos Desconocidos
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:
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.
Juan Esteban Galvis
Estudiante
Erika Gabriela Villanueva Perez de Leon
Estudiante
Gonzalo Gramaglia
Estudiante
Juan David Sánchez
Estudiante
Alejandro Dh
Estudiante
Efraín Girón Romero
Estudiante
José Enrique Pérez Aquino
Estudiante
Cristian Blandon
Estudiante
Rubén Cuello
Estudiante
Carlos Enrique Corona
Estudiante
Adrián de los Reyes
Estudiante
Andrei Perez
EstudianteCreo 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.
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.
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.
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
Abreviatura
Fuente
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.
Es cierto, mejor tener un tipo de glosario, si no está al inicio, que algún índice indique dónde se puede encontrar para que el que quiera o lo necesite lo pueda consultar.
¡Saludos!
"Si el acrónimo es más corto que el término completo..."
¿Puede darse el caso contrario?
Creo que tu te refieres a si el acronimo es mas grande, pero creo que generalmente no sucede. A lo que se refiere esta un poco confuso, la profesora se baso al 100% en el curso de google, esa parte la describen como:
Pero la profesora no expreso la idea por completo o la adapto conforme ella la entendio. (No significa que este mal)
Ejemplos de uso:
World Bank (WB) Mal uso
Ministry of Energy and Water (MEW) Mal uso
Solo si se usa un par de veces, pero es correcto si se usa muchas.
Ghana’s Millennium Development Authority (MiDA) Buen uso
Fuente de los ejemplos
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
