Curso de Introducción al Technical Writing y Documentación de Código
Contenido del curso
Identificación de Audiencia en Escritura Técnica
Importancia de identificar a tu audiencia y fases de la escritura 🎯
Uno de los pilares del technical writing es la identificación de la audiencia a la que va dirigido tu escrito, independientemente de que sea un informe técnico o no.
¿Quiénes van a leer tus escritos? ¿Cuáles son sus perfiles? ¿Qué es lo que saben y qué es lo que no saben? Todas estas son las preguntas más importantes que debes hacer. Con base en las respuestas que obtengas podrás cubrir todas las fases de la escritura de un documento:
Planificación
Redacción
Revisión
En próximas clases profundizaremos un poco más en todas estas fases.
Dicho en otras palabras, definir a tu audiencia no es más que la "adaptación" de tu escritura para cubrir las necesidades, intereses y antecedentes de la gente que leerá tus escritos.
Foto por Clker-Free-Vector-Images en Pixabay
Analiza a tu audiencia 🕵️♀️
En un proceso de documentación global se invierte mucho tiempo y esfuerzo en definir la audiencia, lo hacemos a través de encuestas, análisis de la experiencia de los usuarios, documentación de pruebas, entre otras. Para fines prácticos de este curso, vamos a hacerlo de una manera sencilla, con algunas preguntas básicas que enlisto a continuación:
¿Quién es tu audiencia? ¿Quiénes serán tus lectores?
¿En cuál compañía trabajan? ¿Cuál es su rol?
¿Cuál es su profesión? ¿En qué área son expertas?
¿Qué necesitan? ¿Cuál es su interés por cubrir?
¿Cómo usará tu audiencia la información de tus escritos?
¿Cuál es el perfil técnico de tu audiencia? ¿Qué saben y qué no saben sobre tu tema?
¿Hay alguna limitación técnica entre tu audiencia y tu proyecto de escritura?
Quizá estas preguntas te parezcan muy absurdas, pero te doy un consejo: jamás des por sentado algo. Hay tantas cosas que dejamos pasar de largo porque creemos que son bastante obvias, cuando la realidad es que son de los puntos en los que más debemos de prestar atención. La falta de análisis y la adaptación de la escritura son de los problemas más comunes en documentos profesionales. Dirigirse a un público equivocado puede ser bastante complicado.
Todo lo anterior podría resumirse en una simple ecuación:
Buena documentación = conocimientos y habilidades que tu audiencia necesita - conocimientos y habilidades que tu audiencia tiene
Tipos de Audiencia 👨👩👧👦
Identifica los tipos de audiencia, los roles son una aproximación para definirlos. La división más común es la siguiente:
Expertos: personas que conocen la teoría y el producto por dentro y por fuera.
Técnicos: personas que construyen, operan, mantienen o reparan lo que los expertos diseñan.
Ejecutivos: personas que toman decisiones comerciales, económicas, administrativas, legales, gubernamentales y/o políticas sobre las cosas con las que trabajan los expertos y técnicos.
No técnicos: personas que tienen curiosidad por un asunto técnico específico y quieren aprender sobre él, pero sin ninguna razón específica o práctica.
Las personas dentro de un mismo rol normalmente tienen compatibilidad en ciertas habilidades y conocimientos técnicos. Por ejemplo, la mayoría de ingenieros de software conocen algoritmos, estructuras de programación, rendimiento de algoritmos, notación Big-O y al menos un lenguaje de programación. Sin embargo, el hecho de que conozcan acerca de notación Big-O no es sinónimo de que los roles no técnicos conozcan de qué trata esta.
Otro ejemplo es cuando leemos una publicación en el periódico relacionada con alguna investigación. Este artículo evidentemente usará un lenguaje dirigido a un público no especializado. Por otro lado, el informe de investigación para científicas o profesionales del tema tendrá un aspecto diferente.
Escribir sería más sencillo si todo el mundo compartiera el mismo rol y conocimiento, pero lamento informarte que no es así. Ismael es experto en Ruby. Ana es experta en Android. A Héctor le encanta Linux. Facundo sabe mucho de Python. Con esto quiero decir que los roles son insuficientes, por lo cual, también debes de considerar la proximidad de tu audiencia al conocimiento de cada uno.
Ejemplo: analicemos la audiencia de QIUB 😎
Vamos a hacer un ejemplo de análisis de audiencia para el proyecto ficticio QIUB.
Mi audiencia se divide en:
Ingenieros de Software
Ejecutivos
La proximidad de conocimiento en mi audiencia es la siguiente:
Mi audiencia conoce las API de QIUB que son parecidas a las API de LEXO (otro proyecto ficticio).
Mi audiencia conoce teóricamente el lenguaje de programación Python, pero toda su vida solo han programado proyectos en JavaScript.
Mi audiencia sabe de matemáticas discretas, pero necesitan repasar el tema de árboles.
Para determinar lo que tu audiencia necesita para cumplir la ecuación que te presenté líneas atrás la recomendación es que escribas en una lista todo lo que tu audiencia necesita aprender. Por ejemplo:
Usar la API de QIUB para agrupar productos por categoría.
Usar la API de QIUB para agrupar clientes por sector.
Usar la API de QIUB para agrupar los productos más consumidos.
Siguiendo estos pasos introductorios estoy segura de que tu audiencia será más clara y así evitarás escribir para un público erróneo.
Ejercicio: mejora un texto de introducción a Python 🐍
Imaginemos que el siguiente texto va dirigido a personas que nunca en su vida han programado y que tendrán su primer acercamiento a la programación a través de Python. ¿Cómo lo mejorarías?
"Python es un lenguaje de programación divertido, extremadamente fácil de usar y que en los últimos años se ha vuelto muy popular. Es un lenguaje de programación interpretado cuya filosofía hace hincapié en una sintaxis simple y es multiparadigma, esto nos dice que Python es un lenguaje que soporta más de un paradigma, suponiendo paradigma como modelo de desarrollo, debido a que soporta orientación a objetos, programación imperativa y en menor medida programación funcional. Es interpretado de tipado dinámico y multiplataforma".
¡Deja tu propuesta en los comentarios! En la próxima clase aprenderemos a investigar y hacer entrevistas para recopilar información. 🔜
Juan Carlos García Esquivel
Estudiante
Carlos Rodríguez
Estudiante
Miguel Angel Sosa Posadas
Estudiante
Gonzalo Gramaglia
EstudianteCarlos Rodríguez
EstudianteGonzalo Gramaglia
Estudiante
Eduardo G Mendoza
Estudiante
Alfonso Morán
EstudianteCarlos Rodríguez
Estudiante
carlos alberto ortiz pacheco
Estudiante
María Fernanda Magallanes Z
Estudiantecarlos alberto ortiz pacheco
Estudiante
Josue Alejandro Torres Gonzalez
Estudiante
Eduardo Riveros
Estudiante
Dilan Santiago Ariza Cañon
Estudiante
Jesus Antonio Barradas Maldonado
EstudianteJuan Carlos García Esquivel
Estudiante
Paola Rodriguez
Estudiante
Cristian Blandon
Estudiante
Emily Zavala
Estudiante
Cristian Dario Prieto Avella
Estudiante
Fabián Vega Alcota
Estudiante
Carlos Eduardo Gomez García
Profesor
Aldair Torres Aguilar
Estudiante
Luis Angel Frias Herrera
Estudiante
Cristian Roso
Estudiante
Maided Guadalupe Hernández Ponce
Estudiante
Nicolas Gonzalez
EstudianteLudwing Juan Homero Pérez Tzaquitzal
Estudiante
Jimmy Buriticá Londoño
EstudiantePropuesta
Les comparto mi propuesta de escrito identificando el objetivo del escrito, la audiencia y el alcance de la información 😃.
Objetivo del texto
Introducir a los usuario sin conocimiento previo al lenguaje de programación Python. El texto no pretende dar información profunda sobre el tema simplemente servir como introducción a los conceptos de programación, Python y sus algunas de características.
Análisis previo
Como el texto está dirigido a usuarios no técnicos y es su primer acercamiento a la programación voy a desestructurar el contenido para poder dar un poco más de contexto a la audiencia y sea más digerible, por otro lado quiero dejar de lado la explicación de los paradigmas de programación ya que no están dentro del objetivo y se pueden dejar para más adelante, aunque considero importante mencionarlos de manera general para mejorar el contexto del escrito.
¿Qué es un lenguaje de programación?
Un lenguaje de programación es un medio de comunicación entre el programador que es la persona que se encarga de escribir instrucciones para la computadora que posteriormente esta procesa y ejecuta.
¿Qué es Python?
Python es un lenguaje de programación muy popular esto es debido a que es fácil de usar. Es un lenguaje de programación interpretado esto quiere decir que necesita un programa llamado intérprete el cual toma las instrucciones que el programador escribe y lo traduce a un lenguaje que la computadora entiende y de esta forma realiza cada instrucción escrita por el programador.
¿Por qué elegir Python?
Entre las bondades que Python nos ofrece podemos destacar las siguiente:
Sintaxis simple
Esto se refiere a que el lenguaje que se utiliza para realizar las instrucciones para la computadora es muy parecido al lenguaje natural humano y por tal motivo es sencillo de aprender.
Multiparadigma
Esto quiere decir que tenemos distintas maneras de estructurar y desarrollar nuestro programa, entre las opciones tenemos:
Tipado dinámico
El tipado dinámico se refiere a que cuando declaramos un valor a una variable por ejemplo una variable x con un valor de tipo numérico x=10 esta puede ser sobrescrita con un valor de otro tipo de dato por ejemplo un texto x="hola", en otros lenguajes de programación como esto no es posible y si declaramos una variable con un valor numérico solo podemos cambiar el valor con otro dato de tipo numérico.
Esto significa que podemos utilizar python en diferentes sistemas operativos como Windows, Mac Os, Linux y únicamente necesitamos instalar el intérprete de Python que si recuerdas ayuda a convertir las instrucciones del programador a instrucciones que la computadora puede entender.
Genial :D.
Python es un lenguaje de programación divertido, extremadamente fácil de usar !!!
En los últimos años se ha vuelto muy popular.
Es un lenguaje de programación que ejecuta instrucciones directas sin la necesidad de un compilar como otros lengules como java.
La filosofía hace hincapié en una ++sintaxis simple++ y es multiparadigma los cuales se describen en la siguiente sección:
Imperativo: El programador instruye a la máquina cómo cambiar su estado.
Declarativo: Se declaran las propiedades del resultado deseado, pero no cómo calcularlo.
Python es un lenguaje que soporta más de un paradigmas: 1.- Orientación a Objetos. 2.- Programación imperativa. 3.- Menor medida programación funcional.
Es interpretado de tipado dinámico, sus variables pueden tomar valores de distinto tipo y multiplataforma. 1.- Window. 2.- Lunux. 3.- iOs 4.- Unix
Gracias por colocar puntos aparte y jerarquizar la información 😁
Grandioso aporte.
📌 Fórmula Súper Importante: . Buena Documentación = Conocimientos y Habilidades que tu audiencia necesita - Conocimientos y Habilidades que tu audiencia tiene
En los últimos años, un lenguaje de programación se ha vuelto muy popular gracias a que es divertido y extremadamente fácil de usar. Estamos hablando de Python, un lenguaje con una filosofía muy particular que hace énfasis en la simplicidad y la belleza del código explícito, esto es; que el código sea sencillo de escribir y de leer. Suena muy simple, verdad? ¡Pues en realidad lo es! Además de ser amigable, cuenta con sólidas características en el lado técnico como:
Me gusta la forma en que vendes Python con tu comentario.
Muy buen aporte -:D.
Python es un lenguaje de programación divertido, extremadamente fácil de usar y que en los últimos años se ha vuelto muy popular. Es un lenguaje de programación interpretado, lo cual quiere decir que la computadora lo entiende en el mismo momento en que escribes el código, cuya filosofía hace hincapié en una sintaxis simple y es multiparadigma (puedes usar más de un estilo de programación), debido a que soporta orientación a objetos, programación imperativa y en menor medida programación funcional. Otras de las ventajas de Python es que no tendrás problemas para definir los tipos (String, Booleno, Number) al declarar una variable. Además de que lo puedes correr en distintos sistemas operativos (Linux, Windows, iOS, etc.).
Hola Carlos Alberto, espero estés súper bien. Quería darte feedback como parte de la clase 17 Me encantó tu ejercicio porque expresaste todo lo que decía el párrafo y lo explicaste de una forma muy fácil de entender. A lo mejor lo que yo hubiese hecho para hacerlo más legible hubiese sido cambiar la estructura de párrafo denso y lo hubiese separado o a lo mejor expresar como una lista para que sea más cómodo a la hora de leer, pero en cuanto a contenido me encantó. :fire:
Un saludo
María muchas gracias por tus comentarios, sin duda los tomaré en cuenta para mejorar este skill.
Espero tengas tiempo en otra ocasión de leer alguno de mis post en medium (estos fueron escritos antes de este curso, jajaja)
Saludos...
“Python es un lenguaje de programación divertido, extremadamente fácil de usar y que en los últimos años se ha vuelto muy popular cuya filosofía hace hincapié en una sintaxis simple. Soporta varios modelos de desarrollo ya que es dinámico y multiplataforma”.
El mejor texto, el problema de los otros ejemplos está en que hacen referencias a conceptos muy técnicos para alguien que recién se está acercando a la programación....¿un absoluto novato entenderá que es multiparadigma, lenguaje interpretado, programación orientada a objetos, string booleano etc ?
Python es un lenguaje de programación, es sencillo de aprender, donde con el puedes hacer cosas increíbles, como servidores, inteligencia artificial, aplicaciones de escritorio y mucho mas, es un lenguaje que tiene facilidad para su mantenimiento y su forma de escribir es tan fácil que te va a encantar!
Python es un lenguaje de programación muy intuitivo por que no necesitas dominar el lenguaje de programación para entender una instrucción ya que su sintaxis es simple. Permite solucionar un problema de diferentes maneras y se puede generar programas que se ejecuten en diferentes plataformas plataformas como pueden ser Windows, Linux, Mac, etc. Estos son algunos de los motivos por lo cual en los últimos años se ha vuelto muy popular.
Les comparto mi resumen 😃
¿Que es la audiencia?
La audiencia son aquellas personas que presencian, un acontecimiento, suceso o evento. Por lo general, se relaciona con un grupo numeroso de personas, pero, con que una persona utilice sus sentidos para interactuar con la información que se está presentando, basta para que se considere como audiencia.
¿Para qué definir nuestra audiencia?
Definir nuestra audiencia nos ayuda a adaptar el contenido de nuestro escrito y así cubrir todas sus necesidades, intereses y cuestionamientos posibles.
¿Cómo definir tu audiencia?
Para definir a nuestra audiencia es recomendable realizar un análisis, y este se obtiene al responder algunas preguntas como:
Para simplificar las preguntas:
/* Buena documentación = conocimientos que tu audiencia necesita - conocimientos que tu audiencia tiene. */
La falta de análisis es uno de los problemas más comunes en documentos profesionales ya que al no detectar los aspectos más esenciales de la audiencia, el objetivo de cumplir con sus necesidades no es posible y en su mejor caso el objetivo estaría incompleto o difícil de comprender.
“Asi como en los lenguajes humanos existen muchos idiomas: inglés, español, frances, etc; en informática existen también diferentes idiomas (lenguajes de programación) que se pueden utilizar. Python es uno de ellos, es un lenguaje de programación, extremadamente fácil de usar y que en los últimos años se ha vuelto muy popular.
Es un lenguaje de programación cuya filosofía hace hincapié en una sintaxis simple...”
¡Hola! Comparto mi propuesta:
Python es un lenguaje de programación divertido, extremadamente fácil de usar y que en los últimos años se ha vuelto muy popular. Es un lenguaje de programación interpretado que se ejecuta línea a línea, sin necesidad de una traducción previa al lenguaje de la máquina, es decir, tiene un intérprete que lo va leyendo secuencialmente. Su filosofía hace hincapié en una sintaxis forma de escribir simple y es multiparadigma que se puede usar para múltiples fines o usos, esto nos dice que Python es un lenguaje que soportando más de una propuesta o estilo de desarrollo, comúnmente llamado paradigma. Es interpretado de tipado dinámico y multiplataforma Al programar en Python, no es necesario indicar el tipo de dato que alojará una variable o estructura de datos, lo cual lo convierte en un lenguaje de programación débilmente tipado; además, se puede instalar y ejecutar en cualquier sistema operativo.
¡Saludos! :D
“Python es un lenguaje de programación divertido, extremadamente fácil de usar y que en los últimos años se ha vuelto muy popular. Es un lenguaje de programación que ejecuta las instrucciones dadas directamente, cuya filosofía hace hincapié en una sintaxis simple y es multiparadigma, es decir, que soporta más de un modelo de desarrollo, como: • Orientación a objetos • Programación imperativa • Y, en menor medida, programación funcional. Es interpretado de tipado dinámico (las variables otorgadas ejecutan diversas acciones) y multiplataforma (puede utilizarse en diversos sistemas operativos)”.
No sé hasta que punto las personas que no han programado sepan que es programación orientada a objetos o a funciones. Entonces no sería una buena idea incluir esos términos en este ejercicio. Yo pasaría de explicarlo o si tengo el suficiente talento para explicar cosas complejas de forma simple lo haría.
Vengo de parte de @camilu-png, que por ahora no puede comentar, aquí esta su respuesta al reto:
Python es un lenguaje de programación, es decir, es un lenguaje que nos permite darle instrucciones a una computadora. ¿Pero qué diferencia a python de los demás lenguajes de programación? Porque así como existen diferentes idiomas, existen diversos lenguajes de programación. Una de las principales características de Python es lo parecido que es al lenguaje natural, por lo que lo hace excelente para principiantes. Pero al mismo tiempo es un lenguaje muy completo, permitiendo crear programas desde lo más básico a lo más complejo con diferentes estilos de programación. Permitiéndote crear videojuegos, desarrollar en la web o en aplicaciones de escritorio.
Mi propuesta: . Python es un lenguaje de programación divertido, extremadamente fácil de usar y que en los últimos años se ha vuelto muy popular. Es un lenguaje de programación que se ejecuta a medida que se lee y permite programar de varias maneras, es decir, podemos asimilar objetos de la vida real dentro del lenguaje. Se puede ejecutar en casi cualquier computadora y la forma de escribirlo puede ser muy dura o muy suave.
Aquí va mi versión: “Python es un lenguaje de programación divertido, extremadamente fácil de usar y que en los últimos años se ha vuelto muy popular. Es un lenguaje de programación cuya filosofía hace hincapié en tener sintaxis simple y ser compatible con distintos modelos de programación, como la programación orientada a objetos. Es posible usar Python en distintos sistemas operativos, como Windows o Mac OS”.
"Python ha sido uno de los lenguajes de programación que se ha hecho popular en los últimos años, ya que, aparte de ser fácil de usar, resulta ser divertido mientras aprendes a programar. Al ser un lenguaje de programación interpretado no necesita ser procesado previamente por un compilador para poder funcionar. Otra de sus ventajas es lo fácil y amigable que resulta escribir código gracias a su sintaxis simple y amigable, si alguna vez has escuchado de lo que sufre un programador con los ";" (punto y coma), en Python no sucede ya que no se usa este signo. Puedes aprovechar la versatilidad de Python ya que se puede adaptar a cualquier modelo de desarrollo, ya sea que implementes programación orientada a objetos, programación funcional o programación imperativa"
Python es uno de los lenguajes más divertidos y accesibles de la actualidad. Su filosofía soporta la orientación a objetos, programación imperativa y funcional. Esto te abre las puertas a muchas posibilidades a la hora de solucionar problemas con una sola herramienta, ya que de hecho es multiplataforma y el tipificado se puede revisar inmediatamente durante la ejecución del código.
¡Iniciar con Python puede ser la puerta para hacer realidad todas las ideas que se te ocurran! Python es un lenguaje de programación multiparadigma con una sintaxis sencilla. Al ser multiparadigma te va a permitir crear lo que sea, cuando sea, donde quieras. Esto lo puedes lograr gracias a que soporta la orientación a objetos, programación imperativa y programación funcional.
Phyton es un lenguaje de programacion divertido, que en estos ultimos años ha tenido un aumento en su popularidad, su filosofia es ser: multiparadigma (soporta diferentes formas de dar solucion a un problema) sintaxis simple (forma en como se escribe: que sea facil de interpretar, etc) multiplataforma(web, movil, servidores, etc) tipado dinámico (es cuando la comprobación de tipificación se realiza durante su ejecución en vez de durante la compilación )
Python es un lenguaje de programación divertido, extremadamente fácil de usar y que en los últimos años se ha vuelto muy popular. Es un lenguaje de programación que permite correr instrucciones sin necesidad de procesos de transformación de comandos y cuya filosofía se enfoca en una escritura simple y que puede utilizarse para programar de distintas formas, tales como orientado a objetos, de forma imperativa y en cierta medida en programación funcional. Es posible cambiar los tipos de datos de las variables a medida que avanza el programa, y permite crear programas que funcionan en gran variedad de sistemas operativos.
Definitivamente si llega de forma más clara a una audiencia no técnica.
