No toda la documentación cumple la misma función. Una guía paso a paso que guía a alguien a través de un proceso hace un trabajo completamente diferente al de un artículo de referencia que define una lista de parámetros. Utilizar el tipo de contenido incorrecto para una tarea es una de las razones más comunes por las que la documentación falla a los lectores, incluso cuando la información en sí es precisa.
Este artículo describe cinco tipos de contenido básicos usados en una base de conocimiento bien estructurada, explica el trabajo que realiza cada uno y te ayuda a identificar cuál es el adecuado para cada necesidad. Los primeros cuatro se basan en el ampliamente utilizado marco Diátaxis (tutoriales, guías prácticas, referencia y explicación); La solución de problemas se añade aquí como quinta, ya que el contenido diagnóstico se comporta lo suficientemente diferente a cualquiera de los dos como para merecer su propia definición.
Los cinco tipos principales de contenido
Guías prácticas
Una guía práctica guía al lector a través de una tarea específica de principio a fin. Asume que el lector tiene un objetivo y sabe por qué quiere lograrlo: solo necesita saber cómo. Todo el artículo está organizado en torno a pasos de acción que producen un resultado concreto.
| El trabajo que hace | Permite al lector completar una tarea real. |
| Cuándo usarlo | Cada vez que un lector necesita hacer algo específico — configurar una función, configurar una configuración, completar un flujo de trabajo. |
| Lo que no es | Un tutorial (que enseña), una referencia (que informa) o un artículo conceptual (que explica). Una guía práctica no enseña conceptos; Mueve al lector paso a paso. |
| Reconocible por | Un título orientado a tareas ("Cómo configurar la autenticación de dos pasos"), pasos numerados, un punto de partida definido y un resultado definido. |
Tutoriales
Un tutorial enseña al lector a hacer algo haciéndole a él quien lo haga. El objetivo es aprender, no completar una tarea. Un lector sigue un tutorial para desarrollar comprensión y habilidad, no porque tenga una necesidad inmediata en el mundo real. El tutorial controla el entorno — puede usar datos de muestra, un sandbox o un escenario simplificado diseñado específicamente para el aprendizaje.
Nota de alcance: En la práctica, esta categoría es fácil de sobreutilizar. Si tu base de conocimientos no ofrece realmente un sandbox, un conjunto de datos de ejemplo o un camino de incorporación dedicado, la mayoría del contenido que se etiqueta como "tutorial" es en realidad una guía disfrazada — el lector tiene una tarea real en mente, no un objetivo de aprendizaje abstracto. Reserva el "tutorial" para contenido que realmente enseñe en un entorno controlado; Si no, escribe una guía práctica.
| El trabajo que hace | Fomenta la competencia y la confianza en un usuario nuevo. |
| Cuándo usarlo | Al incorporar nuevos usuarios, introducir una función compleja o ayudar a los lectores a desarrollar habilidades que aún no poseen, de forma genuina a través de un entorno controlado y centrado en el aprendizaje. |
| Lo que no es | Una guía práctica (que resuelve una tarea real), o un artículo conceptual (que explica sin hacer nada). Un tutorial siempre implica acción: el lector debe hacer algo. |
| Reconocible por | Un encuadre orientado al aprendizaje ("En este tutorial, aprenderás cómo..."), un entorno controlado o de muestras, y una declaración explícita de lo que el lector podrá hacer al final. |
Artículos conceptuales
Un artículo conceptual explica cómo funciona algo, qué es algo o por qué algo está diseñado de esa manera. No instruye — informa. El lector se marcha con comprensión, no con una tarea terminada.
| El trabajo que hace | Construye el modelo mental que el lector necesita para usar un producto de forma eficaz. |
| Cuándo usarlo | Al introducir un concepto nuevo, explicar la arquitectura de un sistema o ayudar al lector a entender la razón detrás de una decisión de diseño antes de interactuar con ella. |
| Lo que no es | Una guía o tutorial práctico. Un ensayo conceptual nunca tiene pasos numerados. Explica; No da instrucciones. |
| Reconocible por | Un título orientado a conceptos ("Entendiendo el control de acceso basado en roles"), contenido cargado en prosa, diagramas y ejemplos, y la ausencia de pasos procedimentales. |
Artículos de referencia
Un artículo de referencia proporciona información precisa y estructurada que los lectores consultan, no leen secuencialmente. Es un recurso consultado en medio de una tarea, que no se lee de principio a fin. Los artículos de referencia priorizan la completitud y la precisión por encima del flujo narrativo.
| El trabajo que hace | Ofrece a los lectores acceso rápido a información técnica precisa y completa. |
| Cuándo usarlo | Documentación de la API, listas de parámetros, atajos de teclado, definiciones de códigos de error, glosarios, opciones de configuración — cualquier lugar donde un lector necesite buscar algo. |
| Lo que no es | Un tutorial o guía de prácticas. Los artículos de referencia no guían a los lectores en un proceso. Proporcionan información; El lector decide qué hacer con ella. |
| Reconocible por | Un formato estructurado y predecible (tablas, listas de definición, bloques de código), un patrón consistente entre entradas y un título que señala el comportamiento de búsqueda ("referencia API", "Atajos de teclado"). |
Artículos de resolución de problemas
Un artículo de resolución de problemas ayuda al lector a diagnosticar y resolver un problema. Está organizado en torno a los síntomas y sus soluciones, no en torno a las características del producto. Un lector llega porque algo va mal — el trabajo del artículo es ayudarle a identificar qué es y corregirlo.
A diferencia de una guía práctica, que parte de un objetivo ("Quiero lograr X"), un artículo de resolución de problemas parte de un síntoma ("X no funciona"). Esa distinción — objetivo primero frente a síntoma primero — es la razón por la que la resolución de problemas de contenido merece aquí su propia categoría en lugar de integrarse en guías prácticas.
| El trabajo que hace | Resuelve un problema que el lector está experimentando activamente. |
| Cuándo usarlo | Mensajes de error, comportamientos inesperados, procesos fallidos, problemas comunes de soporte. |
| Lo que no es | Una guía práctica (que asume que las cosas están funcionando) o un artículo de referencia (que proporciona información sin resolver un problema específico). Un artículo de resolución de problemas es diagnóstico: parte de un síntoma, no de un objetivo. |
| Reconocible por | Organización centrada en los síntomas ("Si ves... / Si no puedes..."), lógica condicional, múltiples posibles causas para un solo síntoma y vías de escalada cuando las soluciones del artículo no resuelven el problema. |
Contenido que no encaja perfectamente
Estos cinco tipos cubren la mayor parte de una base de conocimiento, pero no toda. Contenido como preguntas frecuentes, glosarios, notas de versión, resumen de productos o páginas de destino a menudo toma prestado de más de un tipo sin coincidir completamente con ninguno — una FAQ, por ejemplo, se comporta como un artículo de referencia (buscado, no leído de principio a fin) pero está organizada en torno a preguntas en lugar de un esquema estructurado. Tratarlos como excepciones reconocidas en lugar de forzarlos a una de las cinco categorías; Lo que importa es que cada contenido tenga una función clara y singular, como se llame.
Mezcla de tipos de contenido
En la práctica, un solo artículo puede recurrir a más de un tipo de contenido. Una guía práctica podría incluir un breve párrafo conceptual para explicar por qué un paso es importante. Un artículo de resolución de problemas podría incluir una tabla de referencia con códigos de error.
Esto está bien, siempre que el propósito principal del artículo siga siendo claro. Los lectores deben ser capaces de identificar inmediatamente qué tipo de artículo están leyendo y qué obtendrán de él. Un artículo que intenta simultáneamente enseñar, instruir, explicar y solucionar problemas no hará bien ninguna de estas cosas.
Cuando un artículo empiece a servir para demasiados propósitos, divídelo.
Elegir el tipo de contenido adecuado
Cuando te sientes a escribir un nuevo artículo, haz primero una pregunta: ¿qué necesita mi lector para llevarse?
| El lector necesita irse con... | Escribe un... |
|---|---|
| Una tarea completada | Guía práctica |
| Una nueva habilidad o comprensión, adquirida haciendo | Tutorial |
| Un modelo mental o explicación | Artículo conceptual |
| Un dato específico | Artículo de referencia |
| Un problema resuelto | Artículo de resolución de problemas |
Tener esto bien antes de empezar a escribir ahorra un tiempo considerable de revisión más adelante. Un tipo de contenido bien elegido da forma al artículo; Una mala elección significa reescribirla desde cero.