The perils of assumption

One of the challenges in writing useful instructions is walking the thin line of assumed knowledge. Even the simplest of tasks can be made horribly complicated if written for someone who knows absolutely nothing about the subject matter. For example, a seemingly innocuous instruction:

Step 1: To open the file, double-click (click the mouse button twice) it.

Here, the writer is assuming that the reader can identify what a file looks like, is able to navigate the mouse pointer over it (which is only implied by these instructions), and knows which mouse button to press (or that they have a one-button mouse), and that "click" mean to rapidly press-and-release. It's also assumed that the reader might have trouble deciphering the jargon of "double-click," which is parenthetically defined. All in all, that's a lot of supposition. But it's absolutely necessary. If this simple step were distilled until it was irreducible all usefulness would be lost.

On the other hand, it is also possible to assume too much. Wired magazine's User's Guide to Time Travel provides a humorous example:

Building a Gott Loop

1. Scan the galaxy for a loop of cosmic string.

2. When you find one, fly close to it in a massive spaceship. [...]

The bottom line is that all documentation has to make some assumptions, but to make the right ones you need to know your audience well, tailor your documentation to serve them, and position your work so its intent, audience, and purpose are clear. See also "The lowest-common denominator problem" and "Writing for a technical audience."

Posted: August 3, 2003 link to this item, Tweet this item, respond to this item