> ## Documentation Index
> Fetch the complete documentation index at: https://www.mintlify.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Define la audiencia de tu documentación, investiga sus objetivos y nivel de conocimiento, y aplica esos datos para escribir contenido que les sirva.

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.

<div id="define-your-primary-audience">
  ## Define tu audiencia principal
</div>

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.

<div id="research-your-users">
  ## Investiga a tus usuarios
</div>

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.

<div id="talk-directly-to-users">
  ### Habla directamente con los usuarios
</div>

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.

<div id="embed-with-your-support-team">
  ### Intégrate con tu equipo de soporte
</div>

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.

<div id="use-feedback-mechanisms">
  ### Usa mecanismos de retroalimentación
</div>

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](/es/guides/improving-docs) para más información sobre el uso de datos de retroalimentación.

<div id="observe-real-navigation-behavior">
  ### Observa el comportamiento real de navegación
</div>

Las herramientas de repetición de sesiones como [FullStory](https://www.fullstory.com) y [Hotjar](https://www.hotjar.com) 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.

<div id="apply-what-you-learn">
  ## Aplica lo que aprendes
</div>

<div id="write-to-the-right-knowledge-level">
  ### Escribe al nivel de conocimiento adecuado
</div>

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.

```mdx theme={null}
<!-- 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.
```

<div id="match-terminology-to-your-audiences-vocabulary">
  ### Adapta la terminología al vocabulario de tu audiencia
</div>

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.

<div id="adjust-depth-and-structure-to-the-task">
  ### Ajusta la profundidad y estructura a la tarea
</div>

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

<div id="build-audience-awareness-into-your-process">
  ## Incorpora la conciencia de audiencia en tu proceso
</div>

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.

<div id="frequently-asked-questions">
  ## Preguntas frecuentes
</div>

<AccordionGroup>
  <Accordion title="¿Qué pasa si mi documentación sirve a múltiples audiencias?">
    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.
  </Accordion>

  <Accordion title="¿Cómo documento para usuarios técnicos y no técnicos?">
    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.
  </Accordion>

  <Accordion title="¿Con qué frecuencia debo revisar mis suposiciones sobre la audiencia?">
    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.
  </Accordion>

  <Accordion title="¿Cuál es la forma más rápida de identificar brechas en la documentación?">
    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í.
  </Accordion>
</AccordionGroup>


## Related topics

- [Cómo medir y mejorar la calidad de la documentación](/es/guides/improving-docs.md)
- [Cómo estructurar la navegación de la documentación](/es/guides/navigation.md)
- [Cómo mejorar el SEO de la documentación](/es/guides/seo.md)