Having spent a sizable part of my career as a software developer, I have needed to read many, many tutorials. Most of these have been somewhere in the range from “poor” to “abysmal”. Below I will discuss some common problems.
The typical tutorial is written so that the information-to-noise ratio becomes too low, actual understanding is not given, and the reader becomes too reliant on a series of fix steps. Over-detailed instructions on what to do is given, while understanding of why something is done is skipped. Similarly, special cases, alternate roads, even minor variations of the given task, and similar, are left out.
This is not merely dumbing-down, but often out-right idioting-down.
Listings like the following are quite common:
Open the File menu.
Select the New Project Wizard entry.
Enter the name of the new project in the field project name. Ignore all other fields.
Click on the Next button.
Change the value of the field X to [something or other].
...
(For truly extreme beginners, even worse excesses can be found: “Move your mouse to the menu that reads “File”, and click with the left mouse-button, ...”)
To some degree, this might be justified: It takes care of those who want to do a certain thing once and then forget about it, as well as the absolute beginners—and with the inflow of very many developers who are not overly bright... (An unfortunate, but, possibly, unavoidable demographic change as more and more companies produce software of ever growing complexity.) However, it does not help the beginners to gain the mid- and long-term abilities and understanding they need, and it slows down the professional who wants to master an area quickly. Speaking for myself: I also find them boring, demotivating, and often even annoying.
This approach also contains the danger of being incorrect for many users. Consider e.g. telling an absolute beginner using a mouse-less notebook to click his left mouse-button. In the same way, other local variations in configuration, products installed, and similar can cause a tutorial to be faulty.
A special case is localization: I recall e.g. trying to connect an early Knoppixw computer to the Internet using a German manual—as a matter of course I had chosen English as default language, and the endless stream of “Go into [German name]” necessitated a lot of trial-and-error until I had what I wanted. This was the more frustrating, because a good manual would have said “Open a terminal window and enter [language independent application name]”. Notably, as many other Linux users, I would have preferred to work with the terminal anyway.
Exactly how to proceed instead will vary depending on the exact circumstances, including readership and product. A few general tips:
Replace highly specific instructions with an abstraction followed by, if needed, an explanation. Example:
Start the New Project Wizard. (Menu File/New Project Wizard or CTRL-N.)
Do not restrict the user to one road; in particular, users will benefit the sooner they learn to work with keyboard short-cuts. Note how the above example explicitly mentions the short-cut for the wizard.
Explain new concepts as they occur and/or in a separate document with clear links from the tutorial. Above, I would recommend two short info-boxes giving a brief overview of what a project is (in this particular context) and what the project wizard does, respectively.
Be careful to explain the effects of any choices, settings, whatnots: Where will the above project name turn up? Why (hypothetically) was one URL protocol replaced by another?
Entries that are not changed should ideally still be briefly touched upon; however, this can be replaced with a “See X for a more detailed discussion of the available settings.”, or similar.
Ideally, the tutorial should contain sufficiently many links to more detailed discussions that the user who strives for an understanding can reach that understanding without searching for sources on his own.
As in many other contexts, it is important to explain the “why”, not just the “how” and the “what”.
The obvious objection is that this might make for an over-loaded document that does not allow for a quick start. This is true—if done naively. However, by clearly differing (by use of different colors, framed info-boxes, or similar) between the “raw” instructions and the deeper going information, this problem can be avoided. Notably, too lengthy individual explanations can be divided into a short in-document explanation, and a longer one in a separate document. Further, while a “hands-on” approach is something many readers want, it is not what they will benefit from: I have consistently found that when I start off a little slower to take the time to gain a basic understanding of what I am doing, then I have actually achieved more even in the mid-term, sometimes even in the short-term. (This is analogous to the sayings “Measure twice, cut once.”, “Less haste, more speed.”, and so on.)
One “disadvantage” with the approach I suggest: It takes more knowledge and effort to actually write a tutorial this way. The days when any idiot can (and often does) write a tutorial would be over—as would the days of mass-produced tutorials.
Similar remarks and principles apply to most other forms of documentation written today: Even documents claiming to be thorough are often disturbingly superficial. Notably, it is often, literally, possible to find dozens or even hundreds of texts covering the same most elementary basics for every text that goes somewhat deeper—and texts with true depth are truly rare.
Further, many training courses (that often amount to a tutorial with a life tutor) make mistakes very similar, but with the added complication that the amount of effort spent on doing leg-work (e.g. re-typing a piece of code or configuration that is given) severely diminishes the time and energy left for thinking and understanding.
Unlike some writers seem to think, beginners benefit more, not less, from more in-depth tutorials. Obviously, the depth must be geared to the right issues, which will be different for a beginner and an expert user. In both cases, however, time should be spent on discussing and explaining concepts, because only a conceptual understanding will be truly helful—much in line with the adage “Give a hungry man a fish and you feed him for a day; teach him how to fish and you feed him for a lifetime.”.
Consider something as basic as just understanding the difference between the browser, the Web, and Google (some low-end users actually have problems with this): Just straightening this out, once and for all, will have a major impact on a users ability to ask for and understand help, to develop further, to use his browser in a better way, etc. In contrast, to reason that “Some users do not understand this difference; ergo, I will write my tutorial so that it is glossed over.” is inexcusable.
All to often authors fail to make clear what is crucial and what is over-specified detail. Compare “Open the file with Notepad.” with “Open the file in an editor (e.g. Notepad).” for a good example of an over-specification for the alleged benefit of the beginner—which leaves the beginner confused and lacking understanding of what he is doing, and the proficient user annoyed.
A semi-problem with many tutorials is that they focus on the first few steps needed to do something, disregarding that these steps will occur relatively seldom in later work. A Java tutorial may put great emphasis on describing preambles and class definitions, a HTML tutorial may expound on document types and encodings, and so on. These, however, are often things that are of little relevance in later work, because that work will consist of changes to an existing class or document, the creation of a new class or document based on a template (which contains most or all of this code, possibly with a few place-holders), or similar.
This information is valuable, and something that the reader should have an awareness of; depending on the details, possibly even something he needs to know thoroughly. However, it is typically not the most important information, often not information he will use even on a daily basis, and the efforts of the tutorial can be spent better. I, for instance, would be entirely at loss on how to write the preamble of an HTML page without using a reference or a pre-defined template of some kind—but this does not matter, because I do not need to write such preambles. (Note, however, that I do understand the preambles when I see them.) I do need to know how to write the actual HTML—and that I do know.
It is often the case that a tutorial spends most of the text on a “realistic” example, say a “demonstrate JDBC by building an online shop”. The consequence is typically that the core issues that should be taught go under in a mass of irrelevant information and efforts: Most of the work needed to build an online shop with JDBC will have nothing to do with JDBC.
Instead a tutorial should focus on the actual subject matter. In particular, example code should not introduce new concepts not immediately relevant, but rely on as little pre-existing knowledge as possible, minimize scaffolding and noise, and be as to-the-point as is doable. A limited justification, however, can be given to brief examples showing the code in a bigger context: It could, e.g., be beneficial to present a method from an online shop (not the entire shop) that does the immediate abstracting of the JDBC code.
Many tutorials use examples and recommendations that lead the users to bad practices, e.g. failure to abstract, copy-and-paste, magic strings. This is very unfortunate, because many users will consider this acceptable or correct: Example code should be of noticeably above average quality—not quick hacks.
Most examples of actual HTML-snippets, e.g. are amateurish crap (sorry, but the phrasing is justified), including errors like not closing tags properly, not using quotation marks around attributes, using uppercase attribute and tag names, and similar bad habits. Bad, that is, in a beginner—inexcusable, in someone who presumes to teach others.
Anyone can slip and miss the correct syntax every now and then, even in an example—I certainly do. However, many of these authors either make these errors consistently (demonstrating a lack of judgment and knowledge) or with such high a frequency that they must be considered negligent. Examples like (admittedly taken from a HTML 3.2 tutorial, but even modern code often shows similar problems)
<TABLE ALIGN=CENTER WIDTH="80%" BORDER=1 CELLSPACING=10 CELLPADDING=3>
<CAPTION>The Nordic countries</CAPTION>
<TR><TD>Denmark</TD> <TD>Finland </TD> <TD>Iceland </TD>
<TD>Norway </TD> <TD>Sweden </TD> </TR>
</TABLE>
are common.
This is not to be confused with an understandable wish to simplify examples. Not writing javadoc comments, e.g., can usually be excused because the comment would bring little in context, while taking up extra space on the page. Similarly, it may be justified to skip over error handling and special cases—provided that the author explicitly informs the reader that this has been done.
Generally, the more advanced the reader is, the more can be skipped with less comment—while examples intended for early beginners should be kept to the highest standards.
The site http://www.thesitewizard.com/e provides many good examples of how not to write a tutorial. Particular weaknesses:
More or less all entries contains an endless re-hashing of the same content, in various variations, with the actually new contents being hidden deep in the page—and covering possibly a quarter of the raw text. When various link list, disclaimers, whatnot, are factored in, it is even worse.
The articles are very clearly written for idiots, with endless listings along the lines of (exaggerated versions) “Here I will honour you by teaching you how to...”, “It is really, really easy, I promise...”, “Congratulations! You were successful! Good boy!”.
Constant overuse of “I” and “you”. (Cf. this discussion of writing mistakes.)
Unsurprisingly: The detailed-instructions-but-no-understanding approach discussed above.
All-in-all, he manages to stretch what could be covered in one paragraph over ten—while insulting the intelligent reader.
The following is an automatically generated list of other pages linking to this one. These may or may not contain further content relevant to this topic.