User Documentation En este tutorial puede aprender cómo hacer un tutorial.
Un tutorial es una lección que le guía a través de una serie de pasos prácticos. Ofrece una experiencia de aprendizaje mediante la práctica. Es la mejor manera de conocer un tema que todavía no le resulta familiar. Los tutoriales son fundamentales en cualquier documentación: muestran el camino a los recién llegados, guían los primeros pasos, son el escaparate, y ofrecen una experiencia agradable y sencilla de un tema. Uno de los "trucos" para conseguir esto es dejar fuera todo lo que pueda distraer en el proceso de aprendizaje. Por ejemplo:
- Formas alternativas de hacer algo o formas de hacer algo muy específico.
- Referencias completas de todas las opciones y una descripción técnica de su estructura.
- Explicaciones detalladas y antecedentes históricos.
Esa información adicional se ofrece mejor por separado. Evite en la medida de lo posible mezclarla, ya que solo enturbiará el tutorial. Este es el principio fundamental del marco de trabajo Diátaxis, una forma sistemática de mejorar la documentación. Ponga la información adicional mencionada anteriormente en las respectivas guías prácticas, referencias y explicaciones. En las guías prácticas puede encontrar rápidamente cómo conseguir algo específico. En las referencias puede consultar cómo funcionan las cosas, qué opciones tienen y dónde encontrar más información. Con las explicaciones puede profundizar en su comprensión del tema.
Aunque un tutorial ofrece una introducción a un tema, no está dirigido exclusivamente a principiantes. ¡También puede ser una introducción a un tema avanzado! Deje claro al principio de su tutorial qué conocimiento o habilidad se necesita para poder hacer el tutorial.
Si le enseña a alguien a cocinar, tiene que explicar cosas como las técnicas de corte, cómo usar un horno y otras cuestiones básicas de cocina. Empieza con una receta sencilla, preferiblemente algo que fácilmente dé un buen resultado final. Ese resultado final en sí no es el objetivo principal: quiere enseñar algunas habilidades. Esto es lo que hace un tutorial. Alguien que sabe cocinar y quiere hacer algo específico no necesita un tutorial así, sino una receta. Las recetas son las guías prácticas de la cocina.
Paso a paso
Para crear un tutorial:
- Recopile información sobre el tema. Documentación existente, vídeos, etc. Anote las cosas que le resulten confusas o que le haya costado tiempo entender. ¿Hay alguna pregunta sobre el tema en el foro?
- ¿Qué conceptos están involucrados? Hacer un pequeño diagrama puede ayudar. No intente ser exhaustivo, pero deje claro qué es importante para este tutorial y qué no lo es.
- ¿Hay algún conocimiento o habilidad específica necesaria para enseñar en su tutorial?
- Cree un ejemplo en el que pueda usar todos los conceptos y habilidades que quiere transmitir en el tutorial. Haga el ejemplo lo más sencillo posible.
- Defina y escriba los pasos para llegar a un resultado final. Cada paso debe ser reproducible por su alumno.
- Filtre todas las explicaciones, referencias, alternativas y casos especiales; colóquelos en artículos separados.
- Escriba una introducción. ¿Qué aprenderá en este tutorial? Mencione cualquier requisito previo necesario para hacer el tutorial.
- Escriba el resumen. ¿Qué hemos aprendido? También puede mencionar qué pasos siguientes seguir para aprender más.
- Añadir capturas de pantalla con anotaciones para ilustrar las acciones a realizar. Consejo: use números en la captura de pantalla y dé las explicaciones en el texto. Esto facilita la reutilización de su captura de pantalla en traducciones y minimiza el esfuerzo de producir capturas de pantalla específicas para cada idioma.
- Añadir diagramas para explicar estructuras, relaciones y procesos.
- Añadir los artículos que lo acompañan con explicaciones, referencias y guías prácticas.
- Coloque todos los artículos de un tema bajo un artículo de resumen, explicando qué es cada cosa, cómo se relacionan y por dónde empezar.
Ejemplo: Crear y publicar un artículo en Joomla
Como ejemplo, vamos a crear un tutorial sobre cómo crear y publicar un artículo bajo un elemento del menú en Joomla.
Recopilación de información
En nuestro manual de usuario encontrará artículos relevantes bajo "Primeros pasos", "Artículos" y "Menús". A menudo resulta confuso, al empezar con Joomla, que no vea un artículo después de haberlo creado, aunque lo haya marcado como "publicado". Para ver el artículo, tiene que haber un enlace a él. Hay varias formas de crear dicho enlace (como un elemento del menú o una presentación de blog de categoría o colocándolo en la presentación de blog de la página de inicio marcando el artículo como destacado o enlazando desde otro artículo), pero ahora nos centraremos en hacer que el artículo esté disponible a través de un elemento del menú.
Conceptos y habilidades
Tenemos 'contenido', 'artículo', 'menú' y 'elemento del menú'. Tenemos que aclarar esos términos. Mostramos dónde encontrar esas cosas en el menú de administración. Dejamos fuera 'categorías' o 'destacado' en este tutorial.
Requisitos previos
Debe tener acceso al área de administración de un sitio web de Joomla en funcionamiento y saber cómo iniciar sesión.
Objetivo
Nuestro objetivo es aprender a crear un nuevo artículo de Joomla y un nuevo elemento del menú bajo el cual colocaremos nuestro artículo.
Pasos
Siga los siguientes pasos para conseguir nuestro objetivo:
A. Crear un artículo
- Inicie sesión en su panel de administración de Joomla.
- Primero vamos a crear el artículo. Vaya al menú "Contenido" en la parte izquierda y seleccione "Artículos".
- Pulse "Nuevo" para crear un nuevo artículo.
- Introduzca un título y el contenido de su artículo.
- Pulse "Guardar y cerrar" para guardar su artículo.
B. Crear un elemento del menú que enlace al artículo
para mostrar el artículo en el sitio web vamos a crear un elemento del menú que enlace al artículo. Vaya al menú "Menús" en la parte izquierda y seleccione "Menú principal".
- Igual que con un artículo, pulse "Nuevo" para crear un nuevo elemento del menú.
- Introduzca un título para su elemento del menú. Este es el título tal y como aparecerá en el menú. No tiene por qué ser el mismo que el título del artículo. Normalmente es más corto que el título de un artículo para que se ajuste mejor al menú.
- Seleccione un tipo de elemento del menú: bajo "Artículos" seleccione "Artículo único".
- Seleccione el artículo: seleccione el artículo que acabamos de crear.
- Vaya al sitio web y actualice. Felicidades: ahora puede pulsar sobre el elemento del menú para ver su artículo.
Introducción
Escriba la introducción: qué aprenderá en este tutorial y qué requisitos previos son necesarios.
Filtrar información adicional
¿Podemos dejar fuera algo de lo escrito hasta ahora? Bueno, en el paso 2 de la creación de un elemento del menú mencioné que el título del elemento del menú no tiene por qué ser el mismo que el título del artículo. ¿Es esa una adición necesaria para este tutorial? Si no lo es, mejor la dejamos fuera por ahora. Pero da una pista para un artículo más especializado sobre los títulos de artículos y los títulos de menú y cuándo se muestran, que involucre las opciones generales del artículo, la configuración individual del artículo en la pestaña de opciones, la configuración del elemento del menú en la pestaña de opciones del elemento del menú y más. También sería bueno hacer un artículo de tipo referencia sobre cómo funcionan juntos los artículos, las categorías y los elementos del menú; en dicho artículo intente ser completo, enumere todas las posibilidades. Un artículo especializado de tipo guía práctica podría ser: "¿Cómo mostrar el título del artículo?", mostrando la configuración en los ajustes generales del artículo, y en la configuración individual del artículo y del elemento del menú. Un artículo de tipo explicación podría contar algo sobre el trasfondo de por qué Joomla usa "artículo" donde, por ejemplo, WordPress usa "entrada", o cómo se renderiza el artículo en la página final.
Conclusión
Resuma todo en un sumario. Y mencione algunos posibles pasos siguientes para aprender más (como: un tutorial sobre cómo añadir una categoría o una guía práctica sobre el atajo de guardar en el menú).
Imágenes y gráficos
Haga capturas de pantalla que muestren los botones y campos involucrados en la creación de un artículo y un elemento del menú. Marque los botones y campos involucrados.
Para mayor claridad podría añadir un diagrama que muestre cómo se coloca un artículo "bajo" un elemento del menú.
Agregar referencias, guías prácticas y explicaciones
Ponga toda la información e instrucciones adicionales en artículos separados.
Visión general
Si tiene varios artículos sobre un mismo tema, debería hacer un artículo de visión general, explicando cómo se relacionan los artículos y por dónde empezar.
Ejercicio
Empiece a elaborar el tutorial anterior sobre cómo crear y publicar un artículo en Joomla. La mejor forma de aprender es haciendo. Publicaremos un ejemplo de cómo puede quedar esto en el manual de usuario actual de este sitio. Pero estaríamos encantados de publicar tu versión si puedes mejorar la actual.
(este artículo también fue publicado en la Revista de la Comunidad Joomla de febrero de 2025)