Technical Writing

Introducción al Technical Writing

Habilidades necesarias:

• Explicar tecnologías complejas de manera útil para el público objetivo.
• Fuertes habilidades interpersonales.
• Comprender código de lenguaje de programación.
• Aprender tecnologías complejas con relativa rapidez
• Escribir claramente en ingles y en tu idioma natal.

La importancia de identificar a tu público y fases de la escritura

• ¿Para quien?
  • definir a tu audiencia.
• Analiza tu audiencia

  • ¿Quiénes son?

  • ¿En donde trabajan?

  • Profesión

  • ¿Qué necesitan?

  • ¿Cual es el perfil técnico de tu audiencia?

    Buena documentación = conocimientos y habilidades que tu audiencia necesita - conocimientos y habilidades que tu audiencia tiene

Tipos de audiencia

• Expertos
  • Conocen el producto por dentro y por fuera.
• Técnicos
  • Construyen, operan, mantienen o reparan lo que los expertos hacen.
• Ejecutivos
  • Toman decisiones comerciales sobre lo que hacen los técnicos y los expertos.
• No técnicos
  • Personas curiosas que desean saber del producto.

Cómo entrevistar equipos de programación para recolectar información técnica

• Herramientas previas:
  • Datos generales del entrevistado.
  • Breve introducción al tema.
  • Cuestionario con preguntas abiertas e inclinadas a los temas definidos.
  • Espacio para comentarios y/o anotaciones.
• Recomendaciones previas:
  • No presiones.
  • No ruegues.
  • No satures.
  • Sé detallista.

Estructura gramatical

Gramática básica

Sustantivo
Objetos, personas, animales o lugares.

• Alfredo lee un libro.

Pronombre
Palabras que pueden sustituir sustantivos.

• El lo compro ayer.

Adjetivos
Palabra que califica o determina el sustantivo.

• Alfredo es inteligente.

Verbo
Palabra que expresa una acción, proceso o estado.

• Alfredo lee un libro.

Adverbio
Palabra que puede modificar el significado del verbo, de un adjetivo o de otro adverbio.

• Alfredo lee bastante.

Preposición
Palabra invariable que se utiliza para establecer una relación de dependencia entre dos o más palabras.

• El agua llega hasta las rodillas.

Conjunción
Palabra que se utiliza para unir dos o más partes de una oración.

• El amable e inteligente hombre.

Transición
Palabras que ayudan a conectar una oración a otra, una idea con otra, de un párrafo a otro.

• Aprobó puesto que hizo un buen trabajo.

Voz activa y voz pasiva

• Voz activa
  • El estándar para el technical writing.
  • sujeto + verbo + objeto = Voz activa
  • Ejemplos:
    • Ellos hablan el idioma francés.
      • Los actores son ellos.
    • El estudiante edita el archivo.
      • el estudiante es el actor.
• Voz pasiva
  • Objeto + verbo + sujeto = Voz pasiva
  • Ejemplos:
    • el estudiante queda opacado.
  • El idioma francés es hablado por ellos
    • ellos queda opacado.
  • El archivo es editado por el estudiante.

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

• Define desde el principio su significado.
• Usa términos de manera coherente y consistente.
• Usa abreviaturas.
• Usa acrónimos adecuadamente.
  • los acrónimos tienen similitud con las siglas, este puede formarse tanto con la inicial como con la primera parte de la palabra.
• Sugerencias:
  • Si el acrónimo es usado pocas veces, no es necesario definirlo.

Técnicas de escritura fundamentales para documentos técnicos.

Sigue las reglas de George Orwell para escribir con claridad

• Tus frases deben ser claras y efectivas.

A veces escribimos mal porque pensamos mal.

• La documentación corta es más fácil de leer y de darle mantenimiento que la documentación larga.
• Se breve.
  • Divide frases largas en otras más cortas.
• Usa verbos fuertes.
  • Los verbos son los más importantes de una frase.
  • Trata de usar verbos precisos, fuertes y específicos.
  • Ejemplo:
    • Verbo débil: Este bug pasa cuando..
    • Verbo fuerte: El sistema muestra un bug cuando..
• Elimina o sustituye palabras superfluas.
  • Eliminarlas o sustituirlas por palabras más funcionales.
  • Ejemplo:
    • A pesar de que Gerardo no sabe programar.
    • Aunque Gerardo no sabe programar.
• Escribe con las reglas de George Orwell.
  • Nunca uses una palabra larga cuando una palabra corta funciona.
  • Si es posible recortar una palabra, hazlo.
  • Nunca uses voz pasiva, usa voz activa en su lugar.
  • Nunca uses una frase extranjera, una palabra científica o de la jerga si puedes pensar una cotidiana.

Uso correcto de listas para ordenar información

• Tener en cuenta que nuestros lectores no leerán todo nuestro contenido.
• Las listas y las tablas son útiles porque hacen hincapié en elementos de interés.
• Lineamientos generales de las listas
  • Úsalas para resaltar o enfatizar texto.
  • Haz que los elementos de la lista sean paralelos en la redacción.
  • Evita el uso excesivo de listas.
• Elige el tipo de lista correcto
  • Listas con viñetas.
    • Artículos no numerados.
  • Listas numeradas.
  • Listas encrestadas o embebidas.
    • Remplazarlas por listas con viñetas o listas numeradas.
• Inicia las listas con verbos imperativos.
  • Un verbo que indica a alguien hacer algo.
• Crea tablas útiles.
  • Simplifica las tablas.
  • Datos numéricos alineados a la derecha.
  • Palabras o texto alineados a la izquierda.
  • Los encabezados van centrados.

Tipos de párrafos y paso a paso para estructurarlos

• Son la base del documento.
• Son la mínima unidad de redacción que explica y desarrolla el significado de una idea.
• Tienen tres partes:
  • Oración principal.
    • Invierte tu energía en grandes(no de tamaño btw) frases principales.
  • Oraciones argumentativas.
  • Oración final.
• Tipos de párrafo:
  • Procesos / How to
    • Pasos, instrucciones.
  • Cronología de tiempo
    • Secuencia de eventos, Proceso de flujo de trabajo.
  • Ilustración
    • Especifica ejemplos.
  • Clasificación
    • Categorías, Características en común.
  • Definición
    • Características únicas, Definición de un concepto.
  • Descripción
    • Impresión vivida del tema, Imágenes sensoriales.
  • Comparación y contraste
    • Similitudes y diferencias.
  • Causa y efecto
    • Razones y consecuencias para un evento.
  • Argumento
    • Ventajas / desventajas, datos.
  • Párrafo de opinion
    • Puntos de vista y observaciones.
  • Narrativa
    • Historias cortas, experiencias personales.
• Pasos para escribir un párrafo:
  1. Lee y anota los detalles del tema a documentar, Resalta palabras clave.
  2. Haz una lluvia de ideas sobre lo que sabes del tema.
  3. Crea un resumen de palabras eligiendo 2-3 elementos relacionados para generar una idea.
  4. Organiza tu lista decidiendo el orden en el que presentaras tus ideas.
  5. Escribe una frase inicial temática que introduzca el tema de tu párrafo.
  6. Crea una oración para cada idea en tu resumen de palabras, trata de vincular cada frase con su frase temática.
  7. Escribe una oración final que.
     1. Resuma ideas presentadas.
     2. Reafirme la idea principal presentada de una manera diferente.
     3. De una opinión o conclusión.
  8. Revisa tus frases, decide que tan bien se mantienen enfocadas y que tan fácil es leer tu párrafo.
  9. Edita tu párrafo en caso de que tenga errores.

Estándares de documentación de código

Cómo documentar una función de código

• Cada lenguaje tiene su manera de documentar el código.
• Debemos explicar que hace el código.
• Describimos la funciones en términos de entrada y salida.

Buenas practicas de legibilidad par código y comentarios

• Se utiliza un código de muestra para iniciarte rápidamente en el uso de una herramienta.
• Creando un código de muestra correcto:
  • Estar programado sin errores.
  • Realizar la función que decide realizar.
  • Estar listo para producción.
  • Seguir los formatos estándar del lenguaje de programación.
• El único propósito del código de muestra es educar al usuario.
• Código ejecutable.
  • Debes explicar como ejecutarlo, así como las actividades previas para hacerlo.
    • Descargar y/o instalar librerías.
    • Ajustar los valores asignados a las variables.
    • Configurar un IDE
    • Ejecutar comandos.
• Código conciso y comprensible.
  • Tener nombres concisos de clases, métodos y funciones.
  • Ser un código fácil de descifrar.
  • En el caso de que sea un código fuertemente anidado, resaltar las partes importantes para ayudar al lector.
• Código comentado.
  • Comentarios cortos y concisos.
  • Evita comentaros sobre cosas obvias.
  • Expláyate más en código no tan intuitivo de entender.
• Código reutilizable.
  • Todos los requisitos para ejecutar el código de muestra, incluyendo dependencias y configuración.
  • Código que puede ser ampliado o personalizado de manera útil por otros.

Organiza y define el alcance de tu documento

• Define el alcance del documento con un párrafo que define su publico y su objetivo.
• Define explicitamente su audiencia.
• Asegúrate que al inicio de tu documento responda las preguntas de tus lectores desde la pagina uno.
• Escribe un resumen ejecutivo (abstract).
• Preguntas para definir audiencia:
  • ¿Quien?
  • ¿Que deben saber para entender el documento?
  • ¿Que deberían hacer después de leerlo?
• Estructura del documento.
  • Divide tus temas en secciones en las que sea fácil navegar.
• Pensar en el lector como una bodega vacía, que va a llenar con cajas grandes, medianas y pequeñas.

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

• Después de tener un primer borrador, revisarlo para perfeccionarlo.
• Adopta una guía de estilo.
• Escribir en segunda persona (Usar "Tu" en vez de "nosotros").
• Poner circunstancias particulares antes de una instrucción en lugar de después.
• Piensa como tu audiencia.
  • Haz un "boceto" de la persona que puede ser tu público.
  • Piensa en varios de estos bocetos, si solo piensas en uno o dos, puede que tu contenido sea difícil para los demás.
• Lee tu texto en voz alta.
  • Servirá para ver si tu estilo de escritura es el adecuado y si es interesante.
• Vuelve a tu borrador más tarde.

Cómo organizar documentos largos

• ¿Cuando escribir documentos largos?
  • Podemos escribir un documento largo o un conjunto de documentos cortos interconectados.
  • Considera los siguientes puntos.
    • Funcionan mejor como documentos cortos:
      • Guías de instrucciones.
      • Resúmenes introductorios.
      • Guías conceptuales.
      • Todo lo que este dirigido a personas con poca experiencia en el tema.
    • Funcionan mejor como documentos largos:
      • Tutoriales exhaustivos.
      • Guías de mejores practicas.
      • Todo lo que este dirigido a personas que ya tienen experiencia en el tema.
• Organizar un documento.
  • Empezar con un esquema puede ayudar a agrupar los temas.
  • Antes de decirle al lector que haga algo, explica el por qué.
  • Limita cada paso(del esquema) a describir un concepto o completar una tarea especifica.
• Escribe una introducción a tu documento.
  • El tema del que trata el documento.
  • Qué conocimientos previos, teóricos y técnicos, se esperan de los lectores.
  • Lo que el documento no cubre.
• Añade navegación a tu documento.
• Elige los encabezados basados en tareas.
• Agrega una breve introducción bajo cada encabezado.
• Revela información paulatinamente. + Agrega nueva terminología y conceptos.
  • Introduce tablas, diagramas, listas y encabezados.
  • Empieza con ejemplos e instrucciones sencillas y añade paulatinamente cosas más complicadas.

Diseño de documentos

Crea ilustraciones instructivas

• Las ilustraciones permiten al lector entender información compleja.
• Enfoca tu ilustración en el pie de página.
  • Un buen pie de página es:
    • Breve y conciso.
    • Aporta información necesaria.
    • Debe atraer la atención del lector.
• Evita ilustraciones técnicas complejas.
  • Evita ilustraciones que necesitan más de 5 puntos para explicarse.
  • Intentar dividir las ilustraciones complejas en módulos.
• Usa señales visuales.
  • Utiliza figuras para señalar el punto a observar.
• Simplifica tus ilustraciones.
  • Hacer lo más simple la ilustración eliminando información no indispensable.
  • Revisar que los colores y las fuentes sean adecuados para su lectura.