Reassuring the reader, or Doing it right on the wrong side of town

In an earlier post on writing commercial courses (Vogel's 12 Rules for Commercial Course Development) I listed that the three most important questions on the participant or reader's mind were "What do I do first?", "What do I do next?", and "What do I do NOW?". As I've been thinking about it, I think that the third question should really be "How do I know that I'm doing it right?"

When a reader is working in a new area--especially one where the reader has just picked up a lot of new knowledge--the reader is dealing with a lot of uncertainty. Not only is the reader unsure of whether or not they are doing the right thing (and what the correct next thing is), the reader is also concerned about what they just did. In a new field you find it difficult to assess success. Good technical writing provides support for letting the reader re-assure themselves that that they are, in fact, "getting it" and "getting it right."

The official term for this is feedback. However, that doesn't mean you should provide feedback at every step: Feedback, like anything else, is based on the reader's knowledge and expectations.

For instance, if your reader is a programmer and you're outlining some process that involves writing code, it's unnecessary to tell the reader that they must fix any syntax or compile time errors: Programmers know that syntax errors indicate an error. On the other hand, if the programmer is supposed to get an error (or even a warning) at some point in the process then you should advise the reader that that this particular warning or error doesn't represent a problem--precisely because of the reader's expectation that "no errors should occur."

While there is some flexibility in the feedback you provide during the process, it would be an unusual document that wouldn't provide the reader with information about what the final result is. Otherwise, how will the reader know if they got it right (assuming that the process doesn't end with a big flashing message that says "You've succeeded!")?

As always, if you're not sure what to include or what to leave out your first choice is to ask a few representatives of your typical reader. If your representatives are surprised at what they get when they are doing it right then you should include feedback to re-assure the reader; if your reader can easily determine whether they're succeeding or failing without your feedback then you should omit it.

Reading or read

• The Lexicographer's Dilemma: by Jack Lynch
• Intensity by Dean Koontz
• The Klee Universe by Christine Hopfengart, Olivier Berggruen, Peter-Klaus Schuster, and Dieter Scholz
• The Spirit: A Pop-up Graphic Novel by Will Eisner and Bruce Foster
• Every Book Its Reader by Nicholas A. Basbanes