He estado aprendiendo a programar, de vez en cuando, durante un par de años. Así que he probado, probado y / o completado muchos tutoriales diferentes. Ahora tengo muchas ideas aleatorias sobre cómo hacer que los tutoriales sean más fáciles de seguir, más fáciles de aprender, más interesantes y más divertidos.
Aquí hay algunas ideas o características de buenos tutoriales e ideas sobre cómo se podrían mejorar los tutoriales.
Hazlos más visuales 
Utilicé el trabajo muy visual de Alex Grey para ilustrar.
La regla 10 del bien considerado libro Brain Rules es “La visión vence a todos los demás sentidos”.
- ¿Cuál es el mejor libro e idioma para aprender programación de computadoras?
- ¿Es más difícil para un hablante de cantonés aprender inglés o viceversa?
- ¿Cómo se aprende a concentrarse en un ponit?
- ¿Cuál es la mejor manera de aprender pruebas matemáticas?
- ¿Qué debo hacer si no entiendo ninguno de los lenguajes de programación o cosas relacionadas con la computadora en un nivel más profundo pero todavía estoy interesado en las computadoras?
Somos increíbles para recordar imágenes. Escuche información y, tres días después, recordará el 10%. Agrega una foto y recordarás el 65%.
Las imágenes también superan al texto, en parte porque la lectura es muy ineficiente para nosotros. Nuestro cerebro ve las palabras como un montón de pequeñas imágenes, y tenemos que identificar ciertas características en las letras para poder leerlas. Eso lleva tiempo.
Los grandes tutoriales tienen imágenes, diagramas e ilustraciones claras. Si estoy tratando de asimilar algo como cómo funciona el nivel 2 de DOM en JS / HTML, muéstrame.
A menudo es muy difícil leer un párrafo de la jerga técnica y comprender lo que dice incluso el 30%.
Haz un modelo visual para mostrarme cómo funciona algo. Anótalo si ayuda.
Metáforas y analogías
Esto está relacionado con el uso de buenas imágenes. El nuevo conocimiento es más fácil de entender cuando se basa en el conocimiento previo.
Imagine que estoy aprendiendo sobre un marco de Model View Controller (MVC) en la programación. La existencia y las acciones de un MVC no son físicas o tangibles.
Según Wikipedia, MVC es
… un patrón de software para implementar interfaces de usuario. Divide una aplicación de software determinada en tres partes interconectadas, a fin de separar las representaciones internas de información de las formas en que se presenta o acepta la información del usuario. [1] [2] El componente central, el modelo , consta de datos de aplicación, reglas de negocio, lógica y funciones. Una vista puede ser cualquier representación de salida de información, como un gráfico o un diagrama. Es posible tener varias vistas de la misma información, como un gráfico de barras para la administración y una vista de tabla para los contadores. La tercera parte, el controlador , acepta la entrada y la convierte en comandos para el modelo o la vista.
Ok, entonces suena como que el controlador es como un hombre medio. Tal vez el controlador es como un director de escena en una obra. Él le dice a la gente cuando necesitan estar detrás del escenario y cuando necesitan estar en el escenario. Él da instrucciones.
Tal vez el administrador de escenario no es la mejor analogía para un controlador, pero es algo. Si las personas pueden imaginar lo que hace un gerente de escena, quizás podrían entender más fácilmente lo que hace un controlador.
Use ejemplos de cosas que las personas saben para ayudarlas a entender cosas que no saben.
Chistes, historias divertidas, o bromas
Leer y aprender algo nuevo puede volverse aburrido. Muchos autores técnicos no se molestan en condimentar su escritura en absoluto.
Las historias, los chistes y las bromas ayudan a mantener al lector sorprendido, comprometido y positivo mientras trabajan en un tutorial. Los tutoriales divertidos te ayudan a mantener el impulso.
Sección de preguntas y respuestas, ya sea como barra lateral o en los comentarios
Es bastante normal no entender algo mientras se realiza el tutorial. Generalmente no hay manera de contactar al maestro para cubrir su pregunta. Sin embargo, es muy común que otros estudiantes hayan tenido las mismas preguntas.
Los tutoriales casi siempre deben tener algún tipo de comentarios o sección de preguntas y respuestas. Esto permite que los estudiantes se conecten y se ayuden entre sí. También puede agregar mucha profundidad o contenido adicional al tutorial.
CodeAcademy tiene un excelente foro de preguntas y respuestas. Si su código no se ejecuta, es fácil entrar para averiguar por qué.
El New York Times recientemente rediseñó su sección de comentarios como una barra lateral (en lugar de al final de la página). Una buena barra lateral emergente como esta sería una excelente manera de hacer preguntas y respuestas en un tutorial. Podría hacer una pregunta sin perder su lugar / flujo en el texto.
Barra de navegación lateral
Aquí está la barra de navegación del lado derecho en la página de documentación de Twitter Bootstrap ( Cómo empezar · Bootstrap ).
A medida que lee la página, le permite saber dónde se encuentra debido a la navegación lateral (refleja la sección en la que se encuentra). Obtendrá una idea de la longitud de las secciones y podrá saltar o retroceder fácilmente.
Barra de progreso
Esta idea es una extensión de la barra lateral. Algunos blogs están empezando a mostrarle qué tan lejos está a través de un artículo con una barra de seguimiento. Así es como el Daily Beast hace lo suyo.
Puedo ver fácilmente qué artículos de la lista he leído y qué tan lejos estoy del actual.
A veces, cuando estás luchando con una sección de tutorial, sería bueno saber cuánto más tienes que ir o no. La barra de seguimiento de progreso podría darte la sensación de que estás progresando (cuando no sientes que lo estás haciendo).
Fuente grande y clara
Varios blogs recientes y sitios de contenido han mejorado sus fuentes. Medium utiliza 22px y 1.5 líneas de espaciado para su contenido. Esto, junto con una gran página en blanco vacía, hace que sea realmente fácil leer sus artículos.
La legibilidad es un complemento de Chrome que puede hacer que cualquier artículo sea mucho más fácil de leer (fuentes más grandes y aisladas). Parece que usan una fuente incluso más grande que Medium.
Los tutoriales deben imitar estos. El material de aprendizaje no debe ser visualmente difícil de leer. El contenido en sí debe ser la parte difícil.
Ejemplos prácticos
Tango con Django es un tutorial bastante bueno de Django (un marco web de Python). Pero el proyecto que tiene que construir no es interesante o práctico. Lo llamó Rango y es una especie de directorio o sitio de Wiki ( Rango – ¡Bienvenido a Rango! ).
Supongo que muy pocas personas están tratando de aprender a Django para construir un sitio así. Muy poca gente usa un sitio así. El tango con Django sería mucho más aplicable si se estuviera construyendo un simple clon de Reddit o Twitter. Es más fácil sentirse motivado para construir algo que sea similar a las cosas que usas.
Dispuesto a corregir y tener en cuenta los comentarios del lector.
Richard de Stanley escribe un excelente tutorial de Javascript llamado Javascript es Sexy. Claramente sabe bien Javascript y sabe cómo enseñarlo.
A veces sus lectores lo llaman o corrigen sobre algo importante en las secciones de comentarios. Richard colocará la corrección o la nota en el tutorial y agradecerá al lector.
Esto hace que el tutorial sea mejor y te hace confiar más en el autor. Muestra que el autor valora la enseñanza vs. tener siempre razón.
Texto claro de ejemplo
Necesito darle crédito a Richard de Stanley otra vez. Sus ejemplos de código son claros y fáciles de leer. Utiliza el resaltado de sintaxis y los comentarios para mostrar el código que se ejecutará. Esto hace que sea mucho más fácil para los lectores mantener el impulso cuando están aprendiendo algo desafiante y técnico. Hace que los ejemplos sean más fáciles de asimilar. Los ejemplos / muestras deben ser lo más claros posible.
Hablar directamente con usted
Es útil y reconfortante cuando un autor tutorial le hablará directamente. Aunque sabemos que no lo son, se sentirá como un buen profesor en línea que estará justo en la sala con usted. Como si te estuvieran enseñando y solo a ti.
Un buen profesor no se limita a explicar. A veces necesitan entrenar y animarte a lo largo. Incluso pondrán cosas como “Si no entendiste bien el concepto Y, vuelve y lee [los enlaces a la sección correspondiente]”. A lo que podría estar como, “Ok, me tienes profesor, voy a leer eso otra vez”.
Marijn Haverbeke (Javascript elocuente) lo llama a usted por hojear su manual. Tal vez sea un poco sorprendente pero puede ser efectivo.
Las líneas grises son caminos, y los números a su lado son las longitudes de estos caminos. Imagina que necesitamos un programa que encuentre la ruta más corta entre dos puntos en Hiva Oa. ¿Cómo podríamos abordar eso? Piensalo por un momento.
No realmente. No se limite a pasar al siguiente párrafo. Trate de pensar seriamente en algunas formas en que podría hacerlo y considere los problemas a los que se enfrentaría. Al leer un libro técnico, es demasiado fácil simplemente ampliar el texto, asentir solemnemente y olvidar rápidamente lo que ha leído. Si hace un esfuerzo sincero para resolver un problema, se convierte en su problema, y su solución será más significativa.
Secciones cortas
La gente no tiene gran capacidad de atención. Puedes lamentarte de esto o simplemente trabajar con ello. Si una sección de un tutorial va a tomar de 20 a 30 minutos o más para resolverlo, divídalo. No es que tengas menos contenido. Simplemente se dividirá en más secciones. Las secciones más cortas pueden sentirse menos desalentadoras.
Enlaces a tutoriales relacionados o lectura recomendada.
Un buen tutorial no pretende ser el recurso final para todos sobre ese tema. No dudarán en enlazar a otros recursos relacionados o útiles, fuera de su sitio.
(agregaré más como pienso en ellos)