Cómo entender a la audiencia de tu documentación

La documentación escrita para todos a menudo no es útil para nadie. El contenido más claro y preciso aún falla si asume el nivel de conocimiento equivocado, usa terminología desconocida o aborda objetivos que el lector no tiene.

Entender a tu audiencia es la base de una documentación efectiva. Esta guía cubre cómo definir para quién escribes, cómo conocerlos a través de la investigación y cómo aplicar esos conocimientos a tu contenido.

Escribe cada página para un tipo específico de lector. Cuando intentas servir a múltiples audiencias en el mismo contenido, terminas haciendo concesiones: agregando contexto para principiantes que aburre a los expertos, o asumiendo conocimientos que pierden a los principiantes.

Las audiencias comunes de documentación incluyen:

• Nuevos usuarios que aprenden el producto por primera vez, que necesitan orientación, contexto y guía paso a paso
• Desarrolladores que integran tu API, que necesitan precisión técnica, ejemplos de código y material de referencia, no explicaciones generales
• Administradores que configuran el producto, que necesitan detalles sobre configuraciones, permisos y casos límite
• Tomadores de decisiones técnicas que evalúan el producto, que necesitan descripciones generales de la arquitectura, información de seguridad y resúmenes de capacidades

Antes de escribir cualquier página, pregunta: ¿quién está leyendo esto y qué está tratando de lograr? Esas dos preguntas determinan cada decisión que sigue: estructura, profundidad, tono, terminología y qué omitir.

No te bases en suposiciones sobre tu audiencia. Los equipos internos tienen demasiado contexto sobre su propio producto para ser representantes confiables de los usuarios.

Las entrevistas con usuarios revelan información que las analíticas no pueden. Pregunta a los usuarios:

• ¿Cómo describen lo que hace tu producto con sus propias palabras?
• ¿Qué estaban tratando de lograr la última vez que consultaron la documentación?
• ¿Qué les pareció confuso o faltante?
• ¿Qué términos usan para las cosas que hace tu producto?

Esa última pregunta es particularmente valiosa para la documentación. Si los usuarios llaman a tu funcionalidad “webhook” y tú la llamas “event callback” en tu documentación, los usuarios que buscan ayuda no encontrarán tu contenido, y no lo reconocerán como relevante cuando lo hagan.

Los equipos de soporte ven las fallas de la documentación constantemente. Pregúntales:

• ¿Qué temas generan más tickets?
• ¿Dónde se confunden o se atascan los usuarios con más frecuencia?
• ¿Qué dicen los usuarios que esperaban encontrar pero no pudieron?

Esta es a menudo la forma más rápida de encontrar las brechas de documentación de mayor impacto.

Ofrece a los lectores una forma de señalar cuando algo no funciona. Las calificaciones de pulgar arriba/abajo y los campos de comentarios abiertos en las páginas de documentación revelan qué contenido funciona y cuál no. Los comentarios negativos en una página de alto tráfico son una corrección de alta prioridad. Consulta Mejora tu documentación para más información sobre el uso de datos de retroalimentación.

Las herramientas de repetición de sesiones como FullStory y Hotjar muestran exactamente cómo los usuarios navegan por tu documentación. Dónde hacen pausa, dónde vuelven a subir y dónde abandonan las sesiones revela brechas que los usuarios a menudo no reportan directamente.

Calibra tus explicaciones a lo que tu audiencia ya sabe, no a lo que sabe tu equipo.

Un desarrollador que integra tu API no necesita que le expliques qué es una API. Un administrador no técnico que configura tu producto empresarial podría necesitarlo. Define los términos técnicos cuando los introduces por primera vez y enlaza a explicaciones más profundas en lugar de interrumpir cada página con contexto fundamental.

<!-- Define en contexto para audiencias menos técnicas -->
Your API key—a unique token that identifies your account—must be included in every request.

<!-- Omite lo básico para audiencias de desarrolladores -->
Include your API key in the Authorization header of every request.

Usa las palabras que usan tus usuarios. Si tus usuarios llaman a algo “proyecto” y tu producto lo llama “espacio de trabajo”, tu documentación se siente ajena para personas que no han internalizado tu vocabulario interno. Documenta las cosas con los términos que los usuarios buscan, luego introduce la terminología de tu producto junto a ellos.

Las audiencias en diferentes etapas tienen diferentes necesidades:

• Los nuevos usuarios necesitan orientación y seguridad: hitos claros, opciones limitadas y confirmación frecuente de que van por buen camino
• Los usuarios experimentados necesitan escanear rápidamente: estructura consistente, información densa, contexto mínimo
• Los lectores de documentación de referencia necesitan completitud por encima de todo

Entender a tu audiencia no es un ejercicio de una sola vez. Los productos cambian, las audiencias evolucionan y surgen nuevos segmentos de usuarios.

Algunas prácticas que mantienen actualizado el entendimiento de la audiencia:

• Revisa las nuevas páginas con un miembro del equipo de soporte antes de publicar. Identificarán rápidamente dónde es probable que las suposiciones fallen.
• Incluye las suposiciones sobre la audiencia en tu resumen de escritura. Indicar “esta página es para desarrolladores que ya han completado la autenticación” mantiene la escritura enfocada durante la revisión.
• Usa a los nuevos empleados como representantes. Antes de que internalicen el vocabulario interno de tu producto, pídeles que completen una tarea usando solo la documentación. Su experiencia a menudo refleja la de los nuevos usuarios.