Curso de Introducción al Technical Writing y Documentación de Código
Contenido del curso
Entrevistas Efectivas para Documentación de Software
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.
Recordemos que tú eres la persona responsable de interpretar y transferir la información recabada a otras personas. Es por ello que primero debes de conocer lo que sabe el equipo de programación. Este punto también es otro de los pilares del technical writer, así que tienes que pulir tus habilidades para interactuar con personas de este nivel.
Imagen de fancycrave1 en Pixabay
A continuación, te compartiré herramientas y recomendaciones a considerar antes y durante la recopilación de información para que esta sea todo un éxito.
Herramientas previas para recopilar información 🛠
Una vez que ubiques a las programadoras que te ayudarán a recopilar la información para documentar la pieza de software en cuestión, debes comenzar con la preparación de una entrevista, que es la herramienta recomendada para este tipo de actividades y la cual te sugiero que tenga esta estructura:
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.
Además, utilizar otras herramientas como la documentación disponible del software a documentar es un buen arma, principalmente para no hacer preguntas incongruentes al programador. Pregunta si existe alguna documentación, léela con lujo de detalle y así podrás organizar preguntas útiles y enfocadas al contexto de lo que quieres saber del software.
También recuerda que tienes internet. Utiliza esta biblioteca digital para buscar información que creas conveniente y que los programadores suponen que ya conoces. No defraudes las expectativas que tienen de ti.
Una técnica que funciona bastante bien es probar el propio software por tu cuenta. Si está disponible, ¡adelante, pruébalo! Probar su funcionalidad garantiza una mayor orientación hacia dónde enfocarás tu entrevista y, de esta manera, la formulación de nuestras preguntas será más precisa.
Recomendaciones previas a la entrevista 🎙
Es importante tomar ciertas recomendaciones previas a la entrevista:
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.
A nadie le gusta que los saturen con montañas de correos electrónicos y recordatorios. Quizá en un inicio funcione, pero sobre la marcha lo aborrecerás a tal grado que lo único que obtendrás de la programadora será poca o nula participación.
Sé detallista con los programadores. En las reuniones que tengas procura llevar algún detalle que la haga sentir a gusto durante la reunión, de esta manera lograrás que la entrevista sea más ligera.
Haz amistad con los programadores. Esta técnica funciona bastante bien, sé empático y descubrirás que será mucho más fácil obtener información.
Investiga por tu cuenta acerca de la pieza de software que documentarás. Sería un gran error de tu parte llegar e improvisar. Para la programadora será una falta de respeto hacia su tiempo y experiencia. Además, perderás credibilidad.
Tips para recolectar información ✌️
La información recoléctala en entrevistas 1:1 (uno a uno) con el programador, convoca a una reunión proponiendo fecha, horario y lugar adecuado.
Llega puntual, agradece a la programadora por su tiempo y compártele por qué necesitas la entrevista.
Ten a la mano las herramientas que utilizarás, ya sea que escribas en tu laptop o con libreta y bolígrafos. Procura llevar tu smartphone con batería para que puedas grabar la entrevista en formato audio y para que tomes fotografías en caso de que hayan hecho apuntes en algún pizarrón.
No escribas literalmente toda la información que te brindan, toma nota de conceptos técnicos, datos, números e información que consideres importante.
Si te quedaste con dudas en alguna explicación, pídele a la programadora que te replantee la respuesta.
Ten el control de la entrevista. No permitas que se desvirtúe ni que se salga del objetivo acordado.
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.
Para cerrar este capítulo te comparto esta frase de James Baker que va muy ad hoc con este tema:
"La preparación adecuada previene el mal desempeño".
¿Tienes todo listo para tu entrevista? 🤓
Para finalizar escribe en los comentarios cuáles elementos debe tener tu formato de entrevista antes de realizarla. Además, si tienes experiencia realizando este tipo de entrevistas, puedes mencionarnos qué otro tip o recomendación te ha ayudado en tu trabajo.
¡Te espero en el próximo módulo para dar un repaso sobre estructura gramatical!
Juan Esteban Galvis
Estudiante
Juan Castro
Profesor
María Fernanda Magallanes Z
Estudiante
David Felipe Castañeda Rubio
Estudiante
Luis Carlos
Estudiante
Jimmy Buriticá Londoño
Estudiante
Juan Carlos García Esquivel
Estudiante
Kelly Paola González Martínez
Estudiante
Agustin Montoban
Estudiante
Ludwing Juan Homero Pérez Tzaquitzal
Estudiante
Royer Guerrero Pinilla
Estudiante
Juan David Sánchez
Estudiante
José Luis Quintero Cañizalez
EstudianteJuan David Sánchez
Estudiante
Erika Gabriela Villanueva Perez de Leon
Estudiante
Alexander Jimenez Sanabria
Estudiante
Gonzalo Gramaglia
Estudiante
Dilan Santiago Ariza Cañon
Estudiante
DANIEL SUAREZ
Estudiante
José Enrique Pérez Aquino
Estudiante
Angel Mejia
Estudiante
Alejandro Moreno Olaverri
EstudianteDavid Furniel
EstudianteMaría Fernanda Magallanes Z
Estudiante
Joan Alejandro Sánchez Rojas
Estudiante
Carlos Emiliano Buelna García
EstudianteDel 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
Ventajas
Desventajas
Las clases sobre cómo hacer entrevistas en el Curso de Diseño Centrado en el Usuario son super valiosas para complementar esta clase. :ok_hand:
Está genial este aporte Juan Esteban, gracias :D
Para un buen 1:1 según Juan Pablo Buritica (profesor en el curso de Engineering Management)
A la principal herramienta
Objetivos de los 1:1
Tipos de 1:1
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.
Gracias
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
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.
ESTABLEZCA LOS OBJETIVOS DE LA ENTREVISTA
Definir los objetivos de la entrevista a partir de los antecedentes investigados.
DECIDA A QUIÉN ENTREVISTAR
Incluir personas clave de todos los niveles que se vean afectados por el producto en cierta forma.
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.
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:
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.
Tienes razón, el seguimiento es muy importante. Y más cuando se trata de software o hardware, porque su evolución no se detiene y a veces sucede muy rápido. Recordemos que la documentación siempre debe estar actualizada.
Encabezado
¿Por qué motivo es necesario obtener los datos generales del entrevistado y el entrevistador? ¿Qué valor podría obtener de estos datos?
Supongo que la intensión es, si se da el caso, en que una persona ajena llegue a leer el formato y así tener claridad de a quien dirigirse de ser necesaria una aclaración o corrección
@JQuinteroC, makes sense. Muchas gracias.
Considero los siguientes puntos para el formato de entrevista
Si es una documentación técnica de algún desarrollo considero hacer las siguientes preguntas:
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." 👌
“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:
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:
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:
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.
Para mi entrevista seria lo siguiente:
Pre-entrevista:
Entrevista
Eso es lo que logre entender y como yo realizaría la entrevista.
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.
