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

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

7

Voz activa vs. voz pasiva: estándares y estructura de una oración

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

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

4/20

Lectura

Las opciones para recolectar información son un poco limitadas cuando se trata de documentar bloques de código o proyectos de software. Uno de los caminos más seguros es acercarte a platicar con el equipo de programación porque, además de ser especialistas en el tema, son quienes colaborarán contigo en la recolección de información.

...

Regístrate o inicia sesión para leer el resto del contenido.

Aportes 33

Preguntas 1

Ordenar por:

¿Quieres ver más aportes, preguntas y respuestas de la comunidad?

Del curso de “Diseño centrado en el Usuario” (https://platzi.com/clases/diseno-usuario/) tome la siguiente nota:

Entrevista

Es una Técnica Cualitativa → Entre 30 y 60 minutos es lo ideal y profundizar en el porqué y no se deben sugerir respuestas y ser neutral.

Proceso

  1. Selección del lugar
  2. Una sola persona debe entrevistar (Máximo 2)
  3. Preparar el guión de preguntas (Más que cuestionario una conversación sobre ciertos tópicos)
  4. Grabar la entrevista o anotar
  5. Recoger información no verbal (Reacciones, facciones, etc)
  6. Informe de conclusiones

Ventajas

  • Permite recolectar información verbal y no verbal (Corporal)

Desventajas

  • El entrevistador debe estar altamente entrenado
  • Al realizarse fuera del entorno habitual del participante puede afectar a sus respuestas
  • Puede ser costoso
  • La información puede estar sesgada por múltiples factores

Para un buen 1:1 según Juan Pablo Buritica
(profesor en el curso de Engineering Management)

A la principal herramienta

  1. Una reunión con cada programador de tu equipo por una vez semana.
  2. Agenda las reuniones de tal manera que no interrumpa el flujo de los miembros de tu equipo.
  3. No mover las reuniones de un día para otro.

Objetivos de los 1:1

  1. Alineamiento y sincronización.
  2. Establecer una buena relación.
  3. Desbloquear o dar contexto.
  4. Guiar o dirigir decisiones.
  5. Dar atención a tu equipo.

Tipos de 1:1

  1. Agenda predeterminada.
  2. Ponernos al día.
  3. Sesión de retroalimentación.
  4. Como vamos con.
  5. Conocernos mejor.

No abuses de las actualizaciones

En mi experiencia, inicio la entrevista mencionando mi idea o lógica de cómo se realiza cierto proceso, para que la persona que estoy entrevistando, tenga un punto de inicio y no se sienta presionada a comparación si le pido directamente que me explique el proceso con sus propias palabras. Lo considero importante, porque las personas que he entrevistado son introvertidas y se ponen nerviosas por que creen que es una auditoria o que están a prueba, es por ello, como busco que el documento sea una guía ágil para facilitar un proceso, también busco que el proceso para hacer dicho documento sea fácil y ameno.

Les comparto un complemento sobre las entrevistas 😃
¿Qué es una entrevista?
Una entrevista es una conversación con un propósito en específico, en la cuál se usa un formato de preguntas y respuestas, en la entrevista hay que obtener las opiniones del entrevistado estas pueden ser más importantes y reveladoras que los hechos. También hay que tratar de capturar los sentimientos del entrevistado, recuerda que este conoce mejor el producto.

Los cinco pasos para la preparación de una entrevista

  1. ENTÉRESE DE LOS ANTECEDENTES

    Leer y comprender todo lo que pueda sobre los antecedentes del producto, poner especial atención al lenguaje utilizado para comunicarse de la misma manera en la entrevista.

  2. ESTABLEZCA LOS OBJETIVOS DE LA ENTREVISTA

    Definir los objetivos de la entrevista a partir de los antecedentes investigados.

  3. DECIDA A QUIÉN ENTREVISTAR

    Incluir personas clave de todos los niveles que se vean afectados por el producto en cierta forma.

  4. PREPARE AL ENTREVISTADO

    Para preparar a la persona que vas a entrevistar, llame por teléfono o envía un mensaje de correo electrónico con anticipación, de manera que el entrevistado esté preparado, la entrevista debe durar de 45 minutos a 1 hora como máximo sin importar cuánto se quieran extender los entrevistados más allá de ese límite.

  5. DECIDA SOBRE LOS TIPOS DE PREGUNTAS Y SU ESTRUCTURA

    Redacta preguntas para cubrir los aspectos clave que se requieren, las técnicas de interrogación apropiadas son la base de la entrevista. Las preguntas tienen ciertas formas básicas que necesitamos conocer. Los dos tipos básicos de preguntas son abiertas y cerradas. Cada tipo de pregunta puede lograr algo ligeramente distinto, en general se usan preguntas abiertas para iniciar la entrevista y generar confianza y posteriormente se utilizan preguntas cerradas que requieren respuestas más específicas,

Mi formato para entrevistas debe de tener:

  1. Fecha de la entrevista
  2. Nombre, teléfono, e-mail y cargo de la persona a entrevistar
  3. Preguntas preparadas
  4. Preguntas que surgen durante la entrevista (adicionales)
  5. Observaciones
  6. Datos para investigar (conceptos tecnicos etc)
  7. Firma de la persona entrevistada

Pienso que antes de empezar con la entrevista primero obviamente debe haber una presentación y una conversación para romper el hielo y generar empatía

Ademas de la estructura propiuesta habria que averiguar que necesidad viene a satisfacer/problema a resolver el software desarrollado.

Es importante tambien establecer next step y proximo encuentro.

Encabezado

  • Titulo
  • Fecha y hora
  • Entrevistado
  • Datos del entrevistado (Asi puedo luego analizar la data y encontrar datos que compartan los entrevistado para saber mejor cual es mi audiencia)
    Cuerpo
  • Preguntas abiertas
  • Preguntas de selección múltiple
    (Las preguntas me servirán para saber que tanto saben del tema, que opinión y punto de vista tienen sobre un tema)
    Pie de pagina
    Observaciones (Sobre inquietudes y que cosas me dijo indirectamente como gestos, acciones, etc…)

Considero los siguientes puntos para el formato de entrevista

  • Nombre del proyecto a documentar
  • Fecha y hora de la entrevista
  • Nombre del entrevistado
  • Objetivo de la reunión
  • Definición de los puntos a tratar en la reunió
  • Contenido de cuestionario, preguntas puntuales
  • Conclusiones

Si es una documentación técnica de algún desarrollo considero hacer las siguientes preguntas:

  • ¿Quién es el usuario final?
  • ¿Quiénes son los gestores de cambio?
  • ¿Cuáles son las clases que se ocupan?
  • ¿Dónde se encuentra el proyecto?
  • ¿Cuáles son las vistas?
  • ¿Cuáles son los riesgos a considerar para futuras actualizaciones?

En lo personal yo me baso en una plantilla que encontré en la web, se las dejo por si les es de utilidad como a mi:

ad hoc
es una locución latina​ que significa literalmente «para esto».​Generalmente se refiere a una solución específicamente elaborada para un problema o fin preciso y, por tanto, no generalizable ni utilizable para otros propósitos
wikipedia

Me gustó el tip “Una vez que tengas tu reporte de la entrevista, compártelo con la programadora y propón una fecha límite para recibir su retroalimentación y validación.” 👌

  • No solo anotes todo, solo anota lo que necesites, como conceptos técnicos, datos, números e información que consideres importante.

“La preparación adecuada previene el mal desempeño”.

Información del entrevistado
Tema que se va a preguntar
Preguntas mas generales
Preguntas enfocadas
Conclusiones, datos extras u observaciones.

Formato de entrevista para la documentación de código

La recolección de información puede enfocarse en documentar bloques de código o proyectos de software. Una de los métodos más comunes para realizar este trabajo son las entrevistas a los programadores.

El formato convencional de una entrevista contiene los siguientes aspectos:

  • Datos generales del entrevistado, el entrevistador y la fecha.
  • Breve introducción del tema u objetivo de la entrevista.
  • Cuestionario con preguntas abiertas e inclinadas a los temas definidos que te interesan indagar.
  • Espacio para comentarios y/u observaciones.

Es imprescindible solo documentar el software disponible, no documentes código que no exista o que aún no haya sido probado. Sin embargo, puedes probarlo por tu propia cuenta si comprendes el código o proyecto a analizar y sabes cómo configurar el espacio de trabajo para ejecutarlo.

Por otro lado, es recomendable preguntar si existe algún tipo de documentación previa o a mano alzada para comprender el contexto de las funcionalidades o el proyecto a documentar con el objetivo de organizar preguntas que aporten valor al reporte de la entrevista previo a esta.

Por lo tanto, según nuestras habilidades como technical writer:

  • Debemos tener en claro los conceptos técnicos usados por los equipos de desarrollo
  • Debemos explicar lo solicitado en un lenguaje fácil de comprender para la audiencia

Para elaborar la documentación debemos identificar la audiencia de nuestro informe y extraer información del reporte de nuestra entrevista para cubrir las siguientes fases de escritura:

  • Planificación
  • Redacción
  • Revisión

Otras recomendaciones son establecer vínculos con los programadores para facilitar la comunicación y retroalimentación de los reportes al concluir las entrevistas para pulir o corregir detalles.

Ejemplo de formato de entrevista:
1.- Nombre del proyecto.
2.- Fecha y hora de la entrevista.
3.- Nombre del entrevistado.
4.- Objetivo de la reunión.
5.- Cuestionario con las dudas a resolver.
6.- Observaciones.
7.- Envió del resumen de la entrevista por un canal de comunicación al entrevistado.

Datos generales del entrevistado, el entrevistador y la fecha.
Tema u objetivo de la entrevista.
Cuestionario con preguntas que te interesan indagar.
Espacio para comentarios y/u observaciones.
Un café, lápiz y una sonrisa.

Primero debo estar clara del objetivo de la entrevista, saber qué información quiero obtener.
Investigar todo lo que pueda del tema.
Hacer una lista de las cosas que no me quedaron claras o algún tema del que quiera profundizar.
Acordar con la persona que voy a entrevistar la hora y el lugar de la reunión, y comentarle algunas dudas que me gustaría resolver en la entrevista.

Ya en la entrevista me gustaría generar una buena relación con la persona a entrevistar y hacerle las preguntas, mientras tengo un cuaderno o laptop para anotar cosas claves.

Eres la persona encargada de transferir la información recabada Datos generales de entrevistador y entrevistado Breve introducción al tema Objetivo de la entrevista Cuestionario Preguntas abiertas Preguntas a temas específicos Espacio para comentarios y observaciones Antes de la entrevista con el programador documentarse (así evitaras preguntas incongruentes) Probar el software por tu cuenta.

Estructura de un 1:1

Para lograr una entrevista efectiva, ten en cuenta los siguientes puntos:

  1. Prepárate para tu entrevista

    • Considera a quién vas a entrevistar
    • ¿Qué necesitas saber?
    • ¿Con qué información cuento?
  2. Permite que el entrevistado colabore contigo

    • ¿Qué conocimientos son más valiosos?
    • ¿Cómo entiendo el proceso completo?
  3. Toma nota

    • Anota conceptos técnicos, datos, números e información importante
    • Si es posible, graba la sesión

Recuerda respetar el tiempo de los SMEs, sean programadores o expertos en la materia.

Ejemplo de formato de entrevista:

  • Título.
  • Lugar.
  • Fecha y hora.
  • Entrevistador.
  • Entrevistado.
  • Puesto del entrevistado.
  • Conocimientos previos.
  • Lista de equipo o materiales para entrevista.
  • Cliente final.
  • Preguntas con una cantidad máxima de entre 10 - 20 preguntas.
  • Resumen.

Despues de leer las recomendaciones para la entrevista… Los programadores somos “Criaturas”. We are creatureszz ***voz terrible

Buenas! 😃
En mi caso partícular el formato de entrevista más adecuado para un programador es realizarlo de manera remota.
Primero estudiaria el software (como usuari final) y leeria la documentación para plasmar dudas técnicas.
Luego haría un borrador con las preguntas previamentes compartidas al programador para que sepa el tema a tratar.
Creo que esto reduciria los tiempos de entrevista.
Tomaría apuntes de la información relevante que pueda brindarme para luego definir la documentación y enviarsela para el feedback “final”

"No presiones a las programadoras, es evidente que tienen toda la información técnica que tú necesitas, así que es poco probable que una actitud intimidadora sea efectiva.

No ruegues a un programador para que te dé información, no llegarás muy lejos"

Me parecen pésimos estos “consejos”. Ni los programadores tienen “toda la información técnica”, ya que ellos mismos también tienen dudas en algún momento, ni es necesario “presionar” a nadie, ni “ser detallista” en un entorno profesional.

Los programadores y en general, nadie, son seres omnipotentes con los cuales hay que postrarse, hay que tratar a todos con respeto y trabajar más esos “soft skills” y ya.

  • Me funciona dejar claro al solicitar el 1:1 y al inicio de la entrevista dejar claro el objetivo y duración de la misma, esto facilita mantener el foco.

  • Muchas de las preguntas pueden contener un poco del contexto acerca del programa (previamente investigado/probado) lo cual desde acá le deja saber que me he preparado para la misma y me he informado para tener más contexto.

  • Desde mi punto de vista, más que evitar rogar al programador (ambas partes están haciendo su trabajo) creo que recalcar la importancia e impacto que tienen los conocimientos que posee, comunicará la valía de la reunión y cómo esto aporta al producto final.

Según la profesora, estos serían los aspectos más destacables en una estructura de una entrevista:
Datos generales del entrevistado, el entrevistador y la fecha.
Breve introducción del tema u objetivo de la entrevista.
Cuestionario con preguntas abiertas e inclinadas a los temas definidos que te interesan indagar.
Espacio para comentarios y/u observaciones.

Elementos para el formato de entrevista:

  • Resumen del perfil de la persona entrevistada.
  • Lo que ya se sobre el tema tratado.
  • Objetivo de la etrevista (lo que quiero tener claro cuando finalice la entevista).
  • Preguntas puntules y el objetivo de estas.

Muy bien

😎

Los elementos que tengo en mi formato son la fecha de la entrevista, nombre del entrevistado, nombre de la empresa, objetivo, luego procedo a que me expliquen brevemente como funciona el sistema, luego hago las preguntas que preparé, y anotar, eventualmente vayan pasando las preguntas si surgen dudas se hacen inmediatamente, no interrumpo al programador mientras está respondiendo una pregunta.

Creo que el punto numero uno ya una vez esta concertada la entrevista es ser puntual, gran primer paso para iniciar

A esto agregaría, si es posible, hacer grabación de audio para entender el lenguaje corporal de la persona a la hora de hablar de cada tema.

Existen teorías diferentes para como proyectarte con tus compañesros de trabajo o empleados. La que a mi me gusta más es que no somos amigos, no somos familia pero nos respetamos para un bien común, no solo de la empresa o proyecto si no de la sociedad en general si es que el proyecto es el adecuado.

1.- Investigar la aplicación lo mas que se pueda antes de la entrevista, si es posible, conseguir manuales y obtener una cuenta de acceso para pruebas y/o demo.

2.- Programar reunión y enviar agenda para indicar los puntos que se abordarán, si es posible también enviar el cuestionario para que el entrevistado tenga mas claro de que se trata.

3.- Contenido del Cuestionario
a.- Fecha
b.- Nombre del entrevistador
c.- Nombre del entrevistado, rol y datos de contacto (correo, opcional el teléfono y/o extension)
d.- Lista de preguntas puntuales
e.- Observaciones

4.- Al final como toda reunión donde se recaba información que causa algún tipo de impacto, crear un documento y/o correo donde se indique lo abordado en la reunión y que se este de acuerdo de lo que se platico.