Like any engineer, I have many times had to learn something entirely new. What I learned at the university is either obsolete or forgotten. This prompted me to reflect a bit about what makes a good tutorial; how does one best learn things like a new programming paradigm, a new software library or even how to solve differential equations. I talked a bit with my wife who is a teacher by training and she confirmed that there are some basic ideas that are applicable to any tutorial.
A basic idea in pedagogics is that you must practice in order to learn effectively. As an example, when I learned how to write Windows programs (at a mature age) I started with a the very good tutorial in [1]. It is a very good tutorial because:
- It tells you up front in simple terms what you need to know and what not before you continue with the tutorial. (“And if you don’t know what a pointer is, you can either 1) Go find a book or tutorial on C, or 2) just go ahead anyway and screw up a lot. I’d really recommend #1, but most people go with #2…”)
- It uses a light and humorous tone which makes it easy to read. (“Slap the following code into your compiler and if all goes well you should get one of the lamest programs ever written.”)
- Practical application of any new theories and concepts is built into the tutorial for immediate (and sometimes brutally honest) feedback and reinforcement of what you’ve learned.
- It starts from the very beginning with that “hello world” program. (Actually, it is a “Goodbye, cruel world!” program but anyway.)
- All new concepts build upon concepts already introduced and concepts are explained in simpler terms when they are needed.
- There is no unnecessary information; every sentence takes you one step ahead in the tutorial and in your learning process.
- There are illustrations and screen-shots to clarify what is hard to describe as text.
- It at the end actually takes you to a level where you can start doing something useful (like writing a useful Windows application).
- There is a ready-made example that you can go back to and compare your (failed) attempts with to see where you goofed.
A good tutorial is not written to demonstrate what the author knows but to change the behavior of the reader / user in the most effective manner by teaching new applicable skills.
I guess that after all this whining I will be challenged with writing my own tutorial. I might take on that challenge when and if I start understanding the topic myself and if there are enough rainy weekends during the fall (which normally shouldn’t be a limiting factor where I live).
Links
[1] theForger’s Win32 API Programming Tutorial
[2] Writing Tutorials (by kirupa)