November 18, 2009 | Category: Uncategorized

Bad Tutorials

As someone working in technology, I’m faced with a fairly moving landscape. The number of new technologies and ideas that pass through my domain of interest make is so that the skills that I had yesterday might not be useful today, and are probably going to start looking silly tomorrow.

A necessary outcome of that is that technologists rely a great deal on different forms of training material, from full-on seminars to simple tutorials and APIs. It strikes me that a great amount of this material, perhaps the majority, is terrible; lacking the ability to convey meaningful lessons to the reader.

Ignoring the material which is underdeveloped or simply inaccurate, my experience tells me that the next worse kind of material is that which runs through a series of steps: do x, do y, do z, you’re done. While this is certainly better than no material at all, it doesn’t help build any understanding, and that’s the key to any successful tutorial. If you build understanding, you’re doing a much better job.

Rather than simply run through steps, take the time and patience to indicate the goals. What will each step achieve, how exactly does it achieve that goal, and what other outcomes are there in slightly different circumstances? Each step should be there to help build understanding of your domain (by which I mean the fundamental components and ideas underpinning your subject matter), and in doing so ensures that the reader will be able to reason about your domain for themselves much earlier.

An extraordinarily good example of this is something like the Spring Framework manual. Each section introduces concepts with worked examples, alternatives, and consequences. The outcome is that given a small amount of time working with Spring you can fairly well reason about a new class that you’ve never encountered.

Always build on the domain understanding, always underline core concepts and always teach underlying principles, rather than simply stating steps.