What’s a good tutorial?

I intended to write a book review part 2 having read more of the DSL Tookit book but it would at this point only be more of the same. The book goes on describing the Mindmap DSL application and at the same time trying to convey how many different parts of the huge Eclipse Modeling Project fit together. The Mindmap part is fairly comprehensible and good whereas I still have a very hard time grasping much of the rest. I keep wondering why such advanced parts are being mixed with what should be most readers’ first experience of DSL, which in turn probably means that they are not in the position to understand those advanced parts. (If of course DSL isn’t exactly the part of the Eclipse project that they have managed to avoid until now but they understand the rest perfectly.) Enough about the book.

My travails 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 which means that a tutorial like the one in the DSL Toolkit book with a built in practical example should be a good format. 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.

I also think that one of my earlier posts is applicable: 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.

An excellent example of a tutorial from the Eclipse world is the Eclipse Process Framework tutorial [2] that I mentioned in this post. It adheres to many of the bullets above (it is maybe not as funny as the other example but then again, you don’t expect that from people interested in work process modeling).

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).


[1] theForger’s Win32 API Programming Tutorial

[2] Eclipse Process Framework (EPF) Composer – Installation, Introduction, Tutorial and Manual

[3] Writing Tutorials (by kirupa)

Leave a Reply

Your email address will not be published. Required fields are marked *