# Tipos de contenido de documentación (/es/guides/content-types)
No toda la documentación cumple el mismo propósito. Un tutorial que guía a un nuevo usuario a través de su primer despliegue es fundamentalmente diferente de una referencia de API que un desarrollador consulta todos los días. Mezclar estos propósitos en una sola página crea contenido que no cumple bien ninguno de los dos objetivos.
El [framework Diátaxis](https://diataxis.fr) proporciona un sistema práctico para categorizar la documentación según la necesidad del usuario en el momento.
## Los cuatro tipos de documentación [#los-cuatro-tipos-de-documentación]
### Tutoriales (orientados al aprendizaje) [#tutoriales-orientados-al-aprendizaje]
Los tutoriales enseñan a través de la práctica. El objetivo del usuario es aprender algo nuevo, y el objetivo del tutorial es brindarle una experiencia exitosa, no documentar cada opción ni explicar cada detalle.
Un buen tutorial:
* No asume conocimiento previo de la tarea específica
* Guía al usuario a través de un ejemplo completo y funcional de principio a fin
* Minimiza las decisiones: indica a los usuarios exactamente qué hacer en lugar de ofrecer alternativas
* Marca el progreso en hitos significativos ("Ya has configurado la autenticación")
* Explica lo justo para mantener al usuario avanzando, no todo lo que hay que saber
Los tutoriales son el tipo de contenido que más inversión requiere para escribir y mantener, pero tienen un impacto desproporcionado en si los nuevos usuarios tienen éxito con tu producto.
### Guías prácticas (orientadas a tareas) [#guías-prácticas-orientadas-a-tareas]
Las guías prácticas ayudan a los usuarios a lograr un objetivo específico. A diferencia de los tutoriales, asumen que el usuario ya tiene algo de contexto y quiere hacer algo en particular, no aprender un concepto.
Una buena guía práctica:
* Aborda una tarea específica en el título y a lo largo de todo el contenido
* Asume conocimiento previo de los prerrequisitos
* Proporciona una secuencia clara de pasos sin contexto innecesario
* Describe qué hacer, no cómo funciona el sistema internamente
La distinción con los tutoriales importa en la práctica: un tutorial sobre "Primeros pasos con la autenticación" guía a un nuevo usuario a través de todo el proceso paso a paso. Una guía práctica sobre "Rotar tus claves de API" asume que el usuario sabe qué son las claves de API y solo necesita los pasos.
### Referencia (orientada a la información) [#referencia-orientada-a-la-información]
La documentación de referencia describe el sistema de manera precisa y completa. Los usuarios la consultan para buscar algo: no la leen secuencialmente ni están aprendiendo.
Una buena documentación de referencia:
* Prioriza la completitud y la precisión por encima de todo
* Es escaneable: tablas, formato consistente, descripciones cortas
* Evita contenido explicativo o conceptual
* Documenta todo, incluyendo valores predeterminados, límites y casos límite
* Se mantiene cerca de la estructura de lo que documenta (una referencia de API sigue la estructura de la API)
Las referencias de API, las listas de opciones de configuración y las referencias de comandos CLI son todo contenido de referencia.
### Explicación (orientada a la comprensión) [#explicación-orientada-a-la-comprensión]
Las explicaciones profundizan la comprensión de un concepto. Los usuarios las leen cuando quieren entender por qué algo funciona de la manera en que lo hace, no cómo realizar una tarea específica.
Un buen contenido de explicación:
* Aborda el contexto y la motivación detrás de una decisión de diseño
* Reconoce las compensaciones y alternativas
* Conecta conceptos a lo largo del sistema más amplio
* Adopta posturas opinadas cuando es apropiado
Las descripciones generales de arquitectura, las guías de conceptos y las páginas de "cómo funciona X" son todo contenido de explicación. Se distinguen de las guías prácticas en que un lector que termina un artículo de explicación no debería sentir que se le ha dado instrucciones para hacer algo, sino que debería sentir que entiende algo mejor.
## Elige el tipo adecuado para cada página [#elige-el-tipo-adecuado-para-cada-página]
| Pregunta | Tutorial | Guía práctica | Referencia | Explicación |
| -------------------------------------------- | -------------------------------- | ------------------------------- | ----------------------------- | ---------------------- |
| ¿Cuál es el objetivo del usuario? | Aprender a través de la práctica | Resolver un problema específico | Encontrar información precisa | Comprender un concepto |
| ¿Qué nivel de conocimiento tiene el usuario? | Principiante | Intermedio | Experimentado | Cualquiera |
| ¿El contenido está orientado a tareas? | Sí, guiado | Sí, específico | No | No |
| ¿Es secuencial? | Sí | Generalmente | No | No |
Cuando tengas dudas sobre qué tipo corresponde a una página, pregunta: "¿Qué hace el usuario después de leer esto?" Si ha completado una tarea, es una guía práctica o un tutorial. Si ahora entiende algo y puede pasar a actuar en otro lugar, es una explicación. Si ha buscado un detalle específico, es referencia.
## Escritura para cada tipo [#escritura-para-cada-tipo]
### Escribir tutoriales [#escribir-tutoriales]
Establece expectativas al inicio: ¿qué construyen o logran los usuarios al final? Usa componentes `` para el progreso secuencial y celebra la finalización en hitos naturales. Minimiza las decisiones: donde haya múltiples enfoques válidos, elige uno y dilo.
### Escribir guías prácticas [#escribir-guías-prácticas]
Comienza con la tarea en el título: "Cómo configurar webhooks", "Cómo migrar de v1 a v2". Escribe desde la perspectiva del usuario, no del producto. Omite el contexto que no afecta los pasos. Enlaza a contenido de explicación o referencia para los usuarios que quieran entender más.
### Escribir referencia [#escribir-referencia]
Estructura los documentos de referencia alrededor de lo que describes, no alrededor de los recorridos del usuario. Usa un formato consistente en todas las entradas. Cada parámetro, flag u opción debería tener un tipo, un valor predeterminado y una descripción de una línea. Mantenlo escaneable.
### Escribir explicación [#escribir-explicación]
Comienza con la pregunta que estás respondiendo: "¿Por qué funciona la autenticación de esta manera?" o "¿Cuál es la diferencia entre organizaciones y espacios de trabajo?" Reconoce que existen múltiples enfoques y explica por qué el producto toma las decisiones que toma. Enlaza a guías prácticas para los usuarios que quieran actuar sobre lo que han aprendido.
## Consejos para mantener la consistencia de tipos [#consejos-para-mantener-la-consistencia-de-tipos]
* **Asigna un tipo de contenido antes de escribir.** Decidir de antemano moldea todas las demás decisiones de escritura: estructura, extensión, tono, qué incluir y qué excluir.
* **Revisa las páginas con propósitos mixtos.** Las páginas que explican un concepto, incluyen un tutorial y hacen referencia a una lista de opciones, todo a la vez, son difíciles de mantener y de usar. Divídelas o elige un tipo principal.
* **Adapta el framework a tu producto.** Diátaxis es un punto de partida, no una regla rígida. Los productos con estructuras inusuales pueden necesitar enfoques híbridos. El principio subyacente —hacer coincidir el contenido con la necesidad del usuario en el momento— se aplica universalmente.
## Preguntas frecuentes [#preguntas-frecuentes]
No. Las funcionalidades pequeñas pueden necesitar solo una guía práctica y una entrada de referencia. Los tipos describen necesidades que los usuarios podrían tener, no una lista de verificación que debas completar. Comienza con lo que tus usuarios realmente necesitan —generalmente una guía práctica y referencia— y agrega tutoriales y explicaciones donde los usuarios tengan dificultades constantes para empezar o entender algo.
Los tutoriales son experiencias de aprendizaje. El usuario comienza sin conocimiento y termina habiendo construido o completado algo, con el tutorial haciendo la mayor parte del trabajo pedagógico. Las guías prácticas son referencias de tareas. El usuario sabe lo que quiere hacer y necesita los pasos para hacerlo. Un tutorial sobre "Construye tu primera integración" y una guía práctica sobre "Conectar una nueva integración" pueden cubrir acciones similares pero sirven a usuarios completamente diferentes en contextos completamente diferentes.
En la práctica, las páginas a menudo mezclan tipos, especialmente el contenido de primeros pasos que combina tutorial y guía práctica. La pregunta es si la mezcla sirve a los usuarios o los confunde. Si una página necesita tanto enseñar un concepto (explicación) como guiar a través de la configuración (tutorial), una estructura clara de secciones puede funcionar. Si el contenido está demasiado mezclado para organizarse limpiamente, dividirlo en páginas separadas generalmente produce mejores resultados.
Lo suficientemente completa para que los usuarios no necesiten leer el código fuente ni contactar al soporte para entender un parámetro u opción. Cada valor configurable debería tener una descripción, tipo, valor predeterminado y ejemplo. La documentación de referencia que omite casos límite o limitaciones obliga a los usuarios a descubrir esos límites por ensayo y error; eso es una falla de la documentación, no un error del usuario.
## Páginas relacionadas [#páginas-relacionadas]
Copia y modifica plantillas para cada tipo de contenido.
Escribe documentación efectiva con un estilo consistente.
Investiga y define la audiencia de tu documentación.
Organiza la estructura de tu documentación de manera efectiva.
Usa datos y métricas para mejorar la documentación.