Technical Writer

Empiezo usando el producto yo misma si está disponible, porque hacer clic en algo me enseña más en diez minutos que leer una especificación. Hago una lista de todas las preguntas que realmente no puedo responder usándolo: casos límite, estados de error, qué pasa si hago algo en el orden equivocado. Luego llevo esa lista al ingeniero o al product manager que lo construyó, en lugar de pedirle que me explique toda la función desde cero, porque una pregunta concreta obtiene una respuesta concreta y útil, y respeta su tiempo. También leo los tickets existentes, los documentos de diseño o los hilos de Slack sobre la función, porque buena parte del razonamiento detrás de una decisión vive ahí y no en la especificación final. Una vez que tengo un modelo funcional de la función, escribo un esquema breve y lo comparto pronto, antes de haber invertido tiempo en el texto completo, para que cualquier malentendido se detecte cuando todavía es barato de corregir. Hice esto recientemente con un sistema de permisos con varios roles heredados: construí una tabla pequeña que asociaba cada rol con un nivel de acceso antes de escribir una sola frase de la guía real, porque necesitaba entender la lógica yo misma antes de poder explicársela a otra persona.

Edito por etapas en lugar de intentar detectarlo todo en una sola pasada. La primera pasada es estructural: ¿el documento responde a la pregunta con la que llegó el lector, y la información está en el orden que necesita, no necesariamente el orden en que me la explicaron a mí. Compruebo que los títulos funcionen como un índice autónomo, porque muchos lectores escanean en lugar de leer de principio a fin. La segunda pasada es de exactitud: sigo yo misma cada instrucción, paso a paso, exactamente como está escrita, porque es muy fácil saltarse mentalmente un paso cuando ya sabes cómo funciona algo. Así he detectado pasos que faltaban y que habrían bloqueado por completo a un lector. La tercera pasada es de lenguaje: recorto palabras innecesarias, compruebo que la terminología sea coherente con nuestra guía de estilo y glosario, y me aseguro de no haber usado dos términos distintos para lo mismo. Uso Vale para revisiones automáticas de estilo y terminología antes de una revisión humana, lo que detecta muchas pequeñas incoherencias sin que una persona tenga que localizarlas manualmente. Antes de publicar, le pido a alguien que no conoce la función, a menudo de otro equipo, que siga el documento en frío y me diga dónde se atasca.

Parto de la tarea que el lector intenta completar, no de todo lo que yo sé sobre la función. Un desarrollador que integra una API necesita ejemplos de solicitudes y respuestas, detalles de autenticación y códigos de error; no necesita la historia de por qué el endpoint se diseñó de cierta manera a menos que eso afecte a cómo lo usa. Un usuario final que lee un artículo de ayuda necesita pasos claros y capturas de pantalla, y el detalle de implementación técnica solo estorbaría. Cuando no tengo claro quién es la audiencia, se lo pregunto directamente a quien hizo la solicitud en lugar de adivinar, porque escribir para el lector equivocado duplica el esfuerzo, una vez para escribirlo y otra para reescribirlo. Para audiencias mixtas a veces divido un documento en dos: una sección de inicio rápido para quien quiere ponerse en marcha de inmediato, y una sección de referencia debajo para quien necesita el detalle completo. También presto atención a lo que realmente preguntan los tickets de soporte y los foros de la comunidad, porque eso me indica dónde está la confusión real en lugar de dónde supongo que está. Si nadie ha preguntado nunca sobre una sección, suele ser señal de que se puede acortar.

La palanca más importante es hacer que la documentación forme parte del proceso de lanzamiento en lugar de algo que ocurre después. Insisto en que la documentación sea un elemento de la lista de comprobación antes de que se lance una función, no una tarea posterior, porque la documentación escrita después del lanzamiento acaba sistemáticamente despriorizada cuando el equipo pasa al siguiente tema. Trabajo en Markdown con nuestra documentación almacenada junto al código en Git, así que una actualización de documentación puede pasar por la misma pull request que el cambio de código, y los revisores ven ambas cosas juntas. Para las áreas que cambian a menudo, como la documentación de referencia de las API, genero todo lo posible directamente desde la especificación OpenAPI en lugar de escribir a mano un contenido que acabará desincronizándose. También hago una auditoría periódica, revisando las páginas con más tráfico cada trimestre para comprobar que siguen coincidiendo con el producto actual, porque incluso un buen proceso se le escapa algo de vez en cuando. Cuando encuentro contenido desactualizado durante una revisión de tickets de soporte o de feedback, lo corrijo de inmediato en lugar de dejarlo para más tarde, porque una corrección pequeña lleva minutos y una acumulación de documentación obsoleta lleva días.

Estaba documentando una función de exportación de datos donde dos ingenieros me dieron respuestas distintas sobre qué pasaba con los registros eliminados: uno decía que se excluían automáticamente, el otro que se incluían salvo filtrado manual. En lugar de elegir una respuesta al azar esperando que fuera la correcta, hice yo misma una prueba rápida: creé un registro, lo eliminé, y ejecuté la exportación para ver qué pasaba realmente. Eso resolvió la duda factual en unos quince minutos, más rápido que seguir yendo y viniendo por Slack. Resultó que ninguno de los dos ingenieros tenía razón del todo: los registros eliminados se excluían por defecto pero reaparecían si se activaba un filtro concreto, un caso límite que nadie había mencionado. Documenté ese comportamiento específico con claridad, incluyendo el caso límite, y se lo señalé al equipo como algo que valía la pena confirmar que fuera intencional, ya que no era obvio que debiera funcionar así. La lección que saqué es que cuando las fuentes no están de acuerdo, probar el producto real suele ser más rápido y más fiable que intentar arbitrar entre los recuerdos de dos personas sobre cómo se construyó algo.

Un ingeniero quería que la referencia de la API incluyera todos los parámetros internos disponibles en un endpoint, incluidos varios que se usaban para depuración interna y no estaban pensados para desarrolladores externos. Mi preocupación era que incluirlos generaría tickets de soporte de desarrolladores intentando usar parámetros que en realidad no estaban soportados para uso externo, y que saturaría la página para los parámetros que la gente sí necesitaba de verdad. No me limité a decir que no: saqué tres ejemplos de nuestra cola de soporte donde parámetros similares, no documentados pero visibles, habían generado confusión en otra parte de la documentación, para que el argumento fuera concreto y no una simple opinión. Propuse un término medio: mantener limpia la referencia pública, y llevar una página interna separada enlazada desde nuestra wiki de ingeniería para cualquiera del equipo que necesitara la lista completa de parámetros. El ingeniero estuvo de acuerdo en cuanto vio el patrón de los tickets de soporte, y la página interna resultó útil también para el onboarding de nuevos ingenieros. He comprobado que oponerse funciona mejor cuando se respalda con un ejemplo concreto de algo que ya salió mal antes, en lugar de una preferencia general por la simplicidad.

Nuestro equipo de soporte señaló que un paso concreto de configuración, conectar una integración de calendario de terceros, generaba un flujo constante de tickets, unos quince a la semana según su sistema de etiquetado. Leí una muestra de los tickets y noté que la documentación existente asumía que el lector ya sabía dónde encontrar la clave API de su calendario, algo nada obvio para usuarios menos técnicos. Reescribí la sección con un tutorial guiado por capturas de pantalla para los dos proveedores de calendario más comunes, añadí una sección de solución de problemas que abordaba los tres mensajes de error concretos que aparecían con más frecuencia en los tickets, y subí el documento en los resultados de búsqueda del centro de ayuda actualizando el título para que coincidiera con la forma en que los clientes realmente buscaban. Pedí a soporte que etiquetara por separado los tickets relacionados con ese flujo durante las seis semanas siguientes para poder medir el impacto real en lugar de asumir que había funcionado. Los tickets de ese problema concreto bajaron de unos quince a la semana a unos cuatro, y los que quedaban eran problemas realmente distintos, no la confusión que la reescritura buscaba resolver. Vincular la corrección a un antes y después medible fue lo que hizo que la mejora fuera demostrable y no anecdótica.

Mi redacción diaria es sobre todo en Markdown, que prefiero para documentación técnica porque es ligero, funciona bien con el control de versiones, y evita que el formato estorbe al contenido real. He trabajado con configuraciones docs-as-code donde la documentación vive en Git junto al código del producto, los cambios pasan por pull requests, y un generador de sitios estáticos, he usado tanto Docusaurus como MkDocs, construye el sitio publicado a partir de los archivos fuente. Para conjuntos de documentación más grandes y estructurados he usado Confluence, que funciona bien para bases de conocimiento internas pero es menos adecuado para documentación pública versionada, según mi experiencia. Para documentación de API en concreto, trabajo a partir de especificaciones OpenAPI o Swagger siempre que puedo, porque generar el contenido de referencia directamente desde la especificación lo mantiene exacto a medida que la API cambia, en lugar de mantener a mano un documento que puede desincronizarse. Uso Vale para revisiones automáticas de estilo respecto a nuestra guía, y Snagit para capturas de pantalla anotadas cuando un tutorial visual es más útil que solo texto. Me adapto rápido a una cadena de herramientas nueva: lo que más me importa no es una herramienta concreta sino entender el flujo de trabajo subyacente, control de versiones, proceso de revisión, canal de publicación, porque esa estructura se traslada de una herramienta a otra.

Empezaría con una guía de inicio rápido que lleve a un desarrollador de cero a su primera llamada API exitosa en el menor número de pasos posible: autenticación, una única solicitud de ejemplo, y la respuesta esperada, nada más. Los desarrolladores que evalúan si usar una API suelen decidir en los primeros minutos según lo rápido que consiguen que algo funcione, así que esa primera página pesa mucho. Después estructuraría la documentación de referencia por recurso o endpoint, con secciones consistentes para cada uno: descripción, parámetros requeridos, un ejemplo de solicitud, un ejemplo de respuesta, y los códigos de error comunes con lo que los provoca. Mantendría el contenido de referencia lo más cerca posible de una generación automática desde la especificación OpenAPI, para que no se desincronice del comportamiento real de la API. Junto a la referencia, añadiría guías orientadas a tareas para casos de uso comunes que combinan varios endpoints, porque un desarrollador que construye una integración real normalmente necesita saber cómo funcionan varias llamadas juntas, no solo cada una por separado. También incluiría un registro de cambios y una política de versionado clara, porque quienes consumen la API necesitan saber qué cambió y si eso romperá su integración existente antes de actualizar nada.

Siempre que puedo, sigo yo misma cada instrucción exactamente como está escrita, usando un entorno de pruebas limpio en lugar de uno que ya tengo configurado de pruebas anteriores, porque un entorno limpio revela pasos de configuración que faltan y que uno ya ajustado esconde. Para cualquier cosa que implique ejemplos de código, ejecuto el código de verdad en lugar de confiar en que parezca correcto, porque un simple error tipográfico en un ejemplo puede bloquear a un lector mucho más tiempo del que a mí me costó cometer el error. Para afirmaciones técnicas más complejas que no puedo verificar por mi cuenta, como detalles de una arquitectura interna, le pido al ingeniero que la construyó que revise el párrafo concreto en lugar de todo el documento, porque una petición de revisión enfocada consigue una comprobación más cuidadosa que un 'échale un vistazo' sobre una página larga. Mantengo una lista corta de preguntas abiertas durante la redacción en lugar de adivinar esperando acertar, y no publico hasta que están resueltas. Después de publicar, trato los tickets de soporte y el feedback de los lectores como una comprobación continua de exactitud: si varias personas se atascan en el mismo paso, suele ser señal de que las instrucciones no eran claras o de que algo cambió en el producto desde que se escribió el documento, no de que los lectores se equivocaran.