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.
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!
Entrevistas Efectivas para Documentación de Software
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
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,
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.
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...)
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
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." 👌
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.
Antes de realizar una entrevista, el formato debe incluir:
Nombre del entrevistador y del entrevistado.
Fecha, lugar y hora.
Objetivo de la entrevista.
Preguntas claras y ordenadas.
Espacio para escribir las respuestas.
Observaciones y comentarios finales.
Recomendación: preparar las preguntas con anticipación, escuchar atentamente y evitar interrumpir al entrevistado para obtener respuestas más completas.
Crear un objetivo (Lo que necesito o quiero saber).
Desarrollar preguntas en base a la información recolectada que me lleven a cumplir mi objetivo.
Generar confianza con el grupo desarrollador del producto (los programadores).
Entrevista
Seleccionar un desarrollador (programador) para entrevistar, fijando una fecha y lugar para llevar a cabo la entrevista.
Puntualidad y respeto ante el entrevistador, un ambiente de confianza y respeto hace que la entrevista sea mas llevadera.
Tener a la mano las herramientas necesarias para guardar la información a recolectar (recomendable, grabar la entrevista, tomar foto y anotar información esencial).
Realizar las preguntas antes formuladas y analizar las respuestas del entrevistador (puede que a medida que pase el tiempo, surjan nuevas preguntas que complementen la información necesitada) y evitar desviarse del objetivo.
ante alguna duda solicitar una explicación más detallas o menos compleja (términos simples que te ayuden a entender la información).
al terminar, exponer todo la información recolectada para recibir una retroalimentación para futuras entrevistas o el cumplimiento del objetivo
Eso es lo que logre entender y como yo realizaría la entrevista.
