Latest posts by techwriter (see all)
- Hazards of Poorly Written Technical Documentation - December 26, 2016
- Get an ‘A’ on Your Next Research Paper With These 6 Simple Steps - November 28, 2016
- An Amazing and FREE Source of Magazines and Periodicals — ISSUU - November 25, 2016
© 2009-2010 Ugur Akinci
Where do we stop describing the details of a stepped procedure? How “granular” a procedural description needs to be?
EXAMPLE 1: When we tell someone “by using an Allen wrench, tighten the screws A, B, and C” do we need to start with instructions to go get the wrench first?
- Go to your tool box.
- Find an Allen wrench that looks like this [PICTURE]
- Go back to the engine block.
- Tighten the screws A, B, and C
No, of course not. We have to assume a certain level of minimum knowledge on the part of the reader in order not to end up an unnecessarily long list of procedural steps.
EXAMPLE 2: If a speaker cabinet has 4 screws, we do not need to say:
- Tighten screw #1
- Tighten screw #2
- Tighten screw #3
- Tighten screw #4
That would be silly, wouldn’t it?
“Tighten all 4 screws on the front of the speaker cabinet” would be enough.
The more skilled and experienced the readers are, the more they hate to be told in minute detail what to do.
RULE: The more skilled and experienced the readers are, the more they like Checklists instead of detailed procedural steps. Each step of the Checklist would of course be a group of stepped instructions describing how to accomplish a step in detail, written for less-experienced readers. You provide the link from each item of the Checklist to the detailed description so that those who’d like to refresh their memories, can go and reader the detailed procedure. That way you’d be killing two birds with one stone: ou would not be insulting the intelligence of experienced users while not forgetting the needs of the less-experienced ones.
LESSON: make sure you know who your readers are, although I relaize it’s always easy for a tehnical writer to have access to such end-user data. However, it is still useful to make a set of realistic assumptions about the profile of your readers before sittign down and actually writing/designing your document.