27. Tutoriales, ejemplos, recetas y documentación orientada al aprendizaje
27.1 Introducción
No toda documentación técnica se consulta para resolver una duda puntual. A veces el lector necesita aprender: comprender un flujo, familiarizarse con una API, practicar una tarea, incorporar una herramienta o recorrer un ejemplo completo. Para esos casos existen tutoriales, ejemplos y recetas.
La documentación orientada al aprendizaje acompaña al lector de manera progresiva. No solo enumera información: propone un camino, presenta contexto, muestra pasos, explica resultados y ayuda a construir confianza.
En este tema veremos diferencias entre tutoriales, ejemplos, recetas y referencias, y cómo escribir contenido práctico para que una persona aprenda haciendo.
27.2 Documentación orientada al aprendizaje
La documentación orientada al aprendizaje está pensada para personas que todavía no dominan una tarea o herramienta. Su objetivo no es cubrir todos los detalles posibles, sino guiar una experiencia inicial que permita entender conceptos y completar una actividad.
Este tipo de documentación debe cuidar el orden. Si presenta demasiados detalles al principio, puede abrumar. Si omite contexto, el lector puede ejecutar pasos sin entender qué está haciendo. El equilibrio está en enseñar lo necesario en el momento adecuado.
27.3 Formas de aprendizaje documentado
La imagen muestra tutoriales, ejemplos, recetas y guías prácticas como formas de documentación orientada al aprendizaje. Cada una ayuda de manera distinta: el tutorial enseña paso a paso, el ejemplo muestra un caso concreto, la receta resuelve una tarea frecuente y la explicación conecta conceptos.
27.4 Tutoriales
Un tutorial guía al lector a través de una experiencia completa de aprendizaje. Suele comenzar con requisitos previos, presentar un objetivo, avanzar paso a paso y terminar con un resultado verificable.
Un buen tutorial no intenta cubrir todas las variantes. Elige un camino principal para enseñar una idea. Por ejemplo, "Crear la primera reserva de turno usando la API" puede ser un tutorial para desarrolladores que se integran al sistema.
El tutorial debe explicar por qué se realiza cada paso, no solo qué comando ejecutar.
27.5 Ejemplos
Un ejemplo muestra una aplicación concreta de una idea, una API, una regla o un procedimiento. Puede ser breve y enfocarse en una situación específica.
Los ejemplos son útiles cuando el lector ya conoce el concepto general, pero necesita ver cómo se aplica. Por ejemplo, una documentación de API puede incluir una solicitud para crear un turno y una respuesta exitosa.
Un ejemplo debe ser realista, correcto y fácil de adaptar. Ejemplos artificiales o incompletos pueden generar confusión.
27.6 Recetas
Una receta es una guía breve para resolver una tarea frecuente. A diferencia de un tutorial, no necesariamente enseña desde cero. Se enfoca en "cómo hacer algo" de manera directa.
Por ejemplo: "Cómo regenerar una clave de API", "Cómo reprocesar notificaciones pendientes" o "Cómo crear datos de prueba para turnos". La receta debe tener requisitos previos, pasos y resultado esperado.
Las recetas son valiosas para tareas que se repiten, pero no con suficiente frecuencia como para recordarlas de memoria.
27.7 Diferencia con referencia técnica
La referencia técnica enumera información completa y organizada para consulta. Un tutorial enseña un recorrido. Una receta resuelve una tarea puntual. Un ejemplo muestra un caso. Cada formato tiene una función distinta.
Una documentación de API puede tener referencia de endpoints y, además, tutoriales para empezar, recetas para operaciones frecuentes y ejemplos de integración. Mezclar todo sin separar formatos puede dificultar la búsqueda.
27.8 Requisitos previos
Todo contenido de aprendizaje debe indicar requisitos previos: conocimientos, permisos, herramientas, datos, versiones y configuración necesaria. Esto evita que el lector se bloquee en pasos que no puede completar.
También conviene declarar qué no se necesita saber. Por ejemplo, un tutorial introductorio puede indicar que no requiere conocimiento interno de la arquitectura.
27.9 Resultado esperado
Un tutorial o receta debe tener un resultado esperado. El lector necesita saber qué habrá logrado al terminar: una aplicación ejecutándose, una reserva creada, una prueba pasando, una integración funcionando o un informe generado.
El resultado esperado ayuda a verificar avance. También motiva el recorrido porque muestra el propósito concreto del aprendizaje.
27.10 Explicar mientras se hace
La documentación de aprendizaje debe combinar acción y explicación. Si solo contiene pasos, el lector puede repetir mecánicamente sin comprender. Si solo contiene teoría, puede no saber cómo aplicar lo aprendido.
Una buena técnica es presentar un paso, explicar por qué se hace y mostrar cómo verificarlo. Esto permite construir conocimiento mientras se obtiene un resultado práctico.
27.11 Progresión de dificultad
El aprendizaje debe avanzar de lo simple a lo complejo. Primero conviene mostrar un caso exitoso y luego variantes, errores o configuraciones avanzadas.
Si un tutorial empieza con todos los casos especiales, el lector puede perder el hilo. Si nunca muestra casos especiales, queda incompleto para el uso real. La progresión ayuda a equilibrar claridad y profundidad.
27.12 Datos y ejemplos seguros
Los tutoriales y ejemplos suelen usar datos. Deben ser seguros, ficticios y coherentes. No deben incluir datos reales sensibles, credenciales, tokens o información de clientes.
Cuando se usan datos de prueba, conviene indicar cómo crearlos, cómo restaurarlos y cómo limpiarlos. Esto permite repetir el tutorial sin afectar información real.
27.13 Tabla comparativa
| Formato | Objetivo | Ejemplo |
|---|---|---|
| Tutorial | Enseñar un recorrido completo. | Crear la primera integración con la API. |
| Ejemplo | Mostrar un caso concreto. | Solicitud y respuesta para reservar un turno. |
| Receta | Resolver una tarea frecuente. | Reprocesar notificaciones pendientes. |
| Referencia | Consultar información completa. | Lista de endpoints y parámetros. |
27.14 Ejemplo de receta
Una receta para soporte podría llamarse "Cómo reenviar una confirmación de turno". Puede incluir requisitos previos, identificación del turno, verificación de estado, ejecución de la acción y confirmación de envío.
La receta no necesita enseñar todo el sistema de notificaciones. Debe resolver esa tarea específica con claridad, indicando riesgos y resultado esperado.
27.15 Mantenimiento de tutoriales
Los tutoriales se desactualizan cuando cambian pantallas, comandos, datos, APIs o reglas. Por eso, deben revisarse periódicamente y probarse como lo haría una persona nueva.
Una buena práctica es ejecutar tutoriales importantes después de cambios relevantes. Si un tutorial falla, probablemente también fallará la experiencia de aprendizaje de nuevos usuarios o desarrolladores.
27.16 Errores frecuentes
Al crear documentación orientada al aprendizaje suelen aparecer estos errores:
- No indicar requisitos previos.
- Mezclar tutorial, referencia y explicación conceptual sin separación.
- Presentar demasiados casos especiales desde el inicio.
- Incluir pasos sin explicar por qué se realizan.
- No mostrar resultado esperado.
- Usar datos reales o credenciales en ejemplos.
- No probar tutoriales después de cambios del sistema.
27.17 Qué debes recordar de este tema
- La documentación orientada al aprendizaje guía al lector de forma progresiva.
- Los tutoriales enseñan recorridos completos.
- Los ejemplos muestran casos concretos.
- Las recetas resuelven tareas frecuentes de manera directa.
- La referencia técnica sirve para consulta completa, no para enseñar un recorrido.
- Todo tutorial necesita requisitos previos, pasos, explicación y resultado esperado.
- Los ejemplos deben usar datos seguros y mantenerse actualizados.
27.18 Conclusión
Tutoriales, ejemplos y recetas ayudan a que la documentación técnica también enseñe. Permiten que usuarios, desarrolladores y equipos de soporte aprendan tareas concretas con práctica guiada.
En el próximo tema estudiaremos la documentación del código: comentarios, nombres, README y documentación interna.