Saltar al contenido principal
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.

​
Define tu audiencia principal

Cada página debe estar escrita 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.

​
Investiga a tus usuarios

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.

​
Habla directamente con 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.

​
Intégrate con tu equipo de soporte

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.

​
Usa mecanismos de retroalimentación

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.

​
Observa el comportamiento real de navegació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.

​
Aplica lo que aprendes

​
Escribe al nivel de conocimiento adecuado

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.

​
Adapta la terminología al vocabulario de tu audiencia

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 sentirá 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.

​
Ajusta la profundidad y estructura a la tarea

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

​
Incorpora la conciencia de audiencia en tu proceso

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.

​
Preguntas frecuentes

Identifica la audiencia principal de cada página en lugar de intentar servir a todos en el mismo contenido. Para productos con audiencias genuinamente distintas —personas separadas con diferentes objetivos y niveles de conocimiento— considera si tiene sentido tener secciones de documentación o rutas de navegación separadas. Mintlify admite navegación basada en pestañas que puede separar contenido por audiencia sin requerir sitios de documentación completamente separados.
Crea contenido separado para cada uno en lugar de intentar mezclarlos. Una explicación conceptual para un tomador de decisiones no técnico y una referencia de API para un desarrollador que integra tu producto sirven propósitos diferentes y deben ser páginas diferentes. Donde la superposición es inevitable, inclínate hacia la versión más técnica y enlaza a contenido conceptual más ligero para los lectores que lo necesiten.
Cuando lanzas un cambio importante en el producto, cuando tu base de usuarios cambia significativamente, o cuando los patrones de tickets de soporte cambian de maneras que no coinciden con tu documentación existente. Las revisiones trimestrales de analíticas de búsqueda y datos de retroalimentación ayudan a detectar la desviación. Las revisiones más frecuentes con tu equipo de soporte pueden detectarla más rápido.
Pregunta a tu equipo de soporte qué temas abordan con más frecuencia que no están bien cubiertos en la documentación. Esto revela brechas de alto impacto más rápido que cualquier herramienta de analítica. Las entrevistas con usuarios, las analíticas de búsqueda que muestran consultas sin resultados y las repeticiones de sesiones que muestran usuarios escaneando páginas sin encontrar respuestas agregan más profundidad a partir de ahí.