Tipos de documentación: tutoriales, guías prácticas, referencias y explicaciones

Elige el tipo de documentación adecuado para cada página usando el framework Diátaxis: tutoriales, guías prácticas, referencia y explicación.

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 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

​

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)

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)

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 se está documentando (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)

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
• Se permite ser opinado 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 le han dicho que haga algo, sino que debería sentir que entiende algo mejor.

​

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

​

Escribir tutoriales

Establece expectativas al inicio: ¿qué habrán construido o logrado los usuarios al final? Usa componentes <Steps> 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

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

Estructura los documentos de referencia alrededor de lo que se está describiendo, 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

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

• 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

¿Necesito los cuatro tipos de contenido para cada funcionalidad?

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.

¿Cuál es la diferencia entre un tutorial y una guía práctica?

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.

¿Puede una sola página servir para múltiples tipos de contenido?

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.

¿Qué tan detallada debe ser la documentación de referencia?

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

Plantillas de contenido

Copia y modifica plantillas para cada tipo de contenido.

Estilo y tono

Escribe documentación efectiva con un estilo consistente.

Conoce a tu audiencia

Investiga y define la audiencia de tu documentación.

Navegación

Organiza la estructura de tu documentación de manera efectiva.

Mejora tu documentación

Usa datos y métricas para mejorar la documentación.