Technical Writing – How to Avoid Unnecessary Granularity & Details

Technical Writing

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?

  1. Go to your tool box.
  2. Find an Allen wrench that looks like this [PICTURE]
  3. Go back to the engine block.
  4. 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:

  1. Tighten screw #1
  2. Tighten screw #2
  3. Tighten screw #3
  4. 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 read the detailed procedure. That way you’d be killing two birds with one stone: you 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 realize it’s always easy for a technical 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 sitting down and actually writing/designing your document.

2 Comments

  1. ccardimon on March 6, 2009 at 11:29 am

    I am unsure about the “unneeded granularity.” I once removed text that explained what a hard drive is. The person reviewing my work put it back it, saying he just spent hours on the phone convincing a client that her large flat screen monitor was not, in fact, also her hard drive. Turns out her IT dept. stuck her tower under her deck to keep things neat. She never saw it, was not very computer literate, and thought her monitor was, somehow, also her hard drive. It is very important to know your users’ level of expertise.



  2. ccardimon on April 1, 2009 at 1:03 pm

    This post dicusses a similar issue:
    Thriving on ignorance
    http://www.dmncommunications.com/weblog/?p=999