El siguiente texto es una cita de: https://diataxis.fr/tutorials/#writing-a-good-tutorial
Traducción realizada con la versión gratuita del traductor www.DeepL.com/Translator
Permita que el usuario aprenda. Al principio, sólo aprendemos algo haciendo - es como aprendemos a hablar, o a caminar.
Dale a tu alumno cosas que hacer, a través de las cuales pueda aprender. Sólo su alumno puede aprender. Lamentablemente, por mucho que lo desees, no podrás aprender por tu alumno. No puedes obligarle a aprender. Lo único que puedes hacer es que ellos puedan aprender.
Mientras conduces al alumno por los pasos que has ideado, haz que utilice las herramientas y realice las operaciones con las que tendrá que familiarizarse, partiendo de las más sencillas al principio hasta las más complejas.
Tu trabajo consiste en iniciar al alumno, no en convertirlo en un experto. No te avergüences nunca de empezar por el principio: un usuario puede ojear rápidamente lo que no es necesario, pero si necesita algo y no está ahí, corres el riesgo de perderlo por completo. También es perfectamente aceptable que lo que hagas al principiante no sea como lo haría una persona experimentada, o incluso que no sea la forma "correcta": un tutorial para principiantes no es lo mismo que un manual de buenas prácticas.
El objetivo de un tutorial es ayudar al alumno a emprender su viaje con seguridad, no llevarle a un destino final.
La única razón para no bajar el umbral es que decidas que no quieres la responsabilidad de enseñar a los principiantes por debajo de un determinado nivel, o que juzgues que un determinado nivel de habilidad es un prerrequisito razonable para usar el producto en absoluto.
Es importante permitir que el alumno se haga una idea de lo que va a conseguir desde el principio. Además de ayudar a fijar las expectativas, les permite ver cómo se acercan al objetivo final a medida que trabajan. Sorprenderles con el resultado al final disminuirá, y no aumentará, el valor de lo que logren. Es muy agradable revelar conclusiones impresionantes con una floritura, pero debería guardar eso para sus trucos de magia y sus novelas.
Proporcionar la imagen que el alumno necesita en un tutorial puede ser tan sencillo como informarle al principio: *En este tutorial construirás un sitio web simple usando Django y lo desplegarás usando Docker. A lo largo del proceso utilizarás un servicio de de almacenamiento en la nube para el manejo de archivos multimedia, y configurarás tu aplicación para utilizarlo.
Uno de tus trabajos como tutor es inspirar la confianza del principiante. La confianza sólo puede construirse capa a capa, pero es fácil que se pierda. Ayuda a mantener un tono amistoso, así como un uso coherente del lenguaje y una progresión lógica del material. y una progresión lógica a través del material. Sin embargo, el requisito más importante es que lo que se le pida al principiante
lo que se le pide al principiante debe funcionar. El alumno tiene que ver que, cuando siga sus instrucciones, obtendrá los resultados que usted promete. promete.
Es un trabajo duro crear una experiencia fiable, pero eso es a lo que debes aspirar al crear un tutorial.
Es probable que tu alumno esté haciendo cosas nuevas y extrañas que no entiende. No les hagas hacer demasiadas cosas antes de que vean un resultado de sus acciones. En la medida de lo posible, el efecto de cada acción debe estar claro para ellos tan pronto posible. La relación de causa y efecto debe ser evidente. Por último, cada resultado debe ser algo que el usuario puede ver como algo significativo.
Cada paso que el alumno siga debe producir un resultado comprensible, por pequeño que sea.
A menos que tengas mucha suerte, los usuarios de tu tutorial tendrán diferentes niveles de habilidad y comprensión. Es posible que También es posible que utilicen herramientas y sistemas operativos diferentes y no puede confiar en que tengan los mismos recursos o entorno.
Esto hace que la fiabilidad repetible sea extremadamente difícil de lograr, y sin embargo, su tutorial debe funcionar para todos los usuarios, cada vez. siempre**.
No tienes otra alternativa que probar tus tutoriales regularmente para asegurarte de que siguen funcionando como se espera.
Los tutoriales se componen de pasos concretos, no de discusiones abstractas. Sea específico y particular, sobre las acciones y los resultados.
Resista la tentación de introducir la abstracción. Todo aprendizaje va de lo particular y concreto a lo general y abstracto. Es más tarde, después de que un principiante se haya encontrado con múltiples ejemplos concretos, cuando está preparado para ver un patrón en ellos y buscar una explicación abstracta de lo que está sucediendo; hasta ese momento, exigir al alumno que maneje
Hasta ese momento, exigir al alumno que maneje niveles de abstracción antes de que haya tenido la oportunidad de comprender lo concreto es confuso y le supone una carga innecesaria.
Es difícil resistirse a esta tentación, porque una vez que hemos comprendido algo, confiamos en el poder de la abstracción para enmarcarlo ante nosotros mismos, y así es como queremos enmarcarlo ante los demás. Pero, sencillamente, no es así como funciona el aprendizaje o la enseñanza exitosa.
#Ofrecer sólo la explicación mínima, necesaria
**Si el alumno no necesita una explicación para completar el tutorial, no se lo expliques.
Por ejemplo, basta con decir algo como: Usamos HTTPS porque es más seguro. Hay un lugar para la discusión y la explicación extensa de HTTPS, pero no en un tutorial. A veces, incluso esa explicación es más que necesaria.
Puede parecer problemático que le pidamos a un usuario que haga cosas, sin mucha explicación de por qué. En la práctica, para el alumno, rara vez lo es. El alumno está centrado en seguir sus instrucciones y obtener un resultado; su tiempo para querer saber más sobre el por qué de lo que está haciendo vendrá después. Por supuesto, incluya enlaces a material explicativo adicional, si lo considera necesario, pero intente resistir la tentación de interrumpir el flujo de un tutorial divagando en la explicación.
Su trabajo consiste en guiar al alumno hacia una conclusión satisfactoria. Puede haber muchas desviaciones interesantes a lo largo del camino (diferentes opciones para el comando que está utilizando, diferentes formas de utilizar la API, diferentes enfoques a la tarea que está describiendo) - ignórelas. Su guía debe permanecer centrada en lo que se requiere para llegar a la conclusión, y todo lo demás puede dejarse para otro momento.
Esto ayuda a que tu tutorial sea más corto y nítido, y evita que tanto tú como el lector tengáis que hacer un trabajo cognitivo extra.