Don’t Write Tutorials

Tutorials are one of the worst ways to learn new information available to a programmer. In part, this is due to failures inherent to the very concept of a tutorial itself — typically designed to be oversimplified, direct demonstrations of a very specific technique or concept, they generally lack anything but superficial, “how to” utility. Any explanation or background that may exist is often incomplete. But this is just a natural problem arising from what a tutorial generally is. In capable hands, used appropriately some tutorials are worthwhile sources of information. The larger problem with tutorials is that there are just so many of them, and most of them are written by people who at best have only a passing understanding of the subject. Frequently the author lacks even that basic foundation, and just thinks he or she understands the material (see “Unskilled and Unaware of It”).

Writing tutorials on a subject you’ve only just barely grasped yourself is folly. Consider an analogy: as a college freshmen who has just passed his Calculus I final, would you honestly consider yourself capable of drafting the textbook for next year’s class? I would hope not; to believe as much would be a grand display of hubris.

Information is dangerous to a beginner. A beginner, by definition, doesn’t really know what he or she is doing. Beginners are not in the position to be able to determine if a particularly bit of information is useful or correct — and so, they do the only thing that is reasonable and assume it must be. Writing tutorials contributes to the already massive store of information that’s available for a bumbling neophyte to stumble across, and if that information is anything less than excellent, that tutorial just adds to the noise.

In short, tutorials should only be written by people who are very experienced — indeed, experts — in the problem domain. Even then there are dangers; just because somebody knows the subject well does not mean they have the requisite communications skill to pass that information on in a clear, understandable format. All of us who have been through college can recall at least one professor who, while he may have known his stuff, couldn’t teach worth a damn. Writing is hard, and writing a good tutorial is particularly hard.

You need to know the material backwards and forwards, even the material you are not explicitly writing about, because every detail of your code and your prose will be absorbed into the mind of somebody who is woefully impressionable and naive. You cannot take shortcuts, you cannot have any doubt. You must be willing to submit your work for review among your peers, willing to field the criticism, both good and bad, and willing to provide the research that backs up any points you’ve made that are contended by the reviewers. You must be a master of your craft (such that somebody besides yourself recognizes this fact) or you will do more harm than good.