David Szpunar: Lead Engineer, PC Help Services

David's Church Information Technology

September 13th, 2007 at 7:51 am Print This Post Print This Post

Manual Humor

In my Technical Writing class, someone brought up the point in the discussion forums that many manuals are either to broad for a novice to comprehend, or too detailed and frustrate experts just looking for a quick reference and trying to skim. I decided to reply with an example showing how a nested list could help provide details for a novice while still being easy to skim for an expert. And, of course, I decided to throw in a touch of ironic humor since I was making up the example anyway. It received a good response, and and thus I pass it on to you as the remainder of this post (some text styles have not carried over from the original example, but I’m not illustrating my point for class here so it doesn’t lose much):

I do think that in some cases, instructions could be improved if they were divided up with different emphasis. So high-level stuff would be large and in one style, with the smaller steps broken down in a smaller area for those that needed them. Most instructions do use a table of contents and/or headings to do something like this, but I think adding levels could in some cases help. For example:

Typing Text in the Eye Dee Ten Tee Program

For ID10Tsnovices or advanced users :-)

  • Big Main Heading
    • Creating a document
      1. Push the button
        • First, hold your finger in front of the circle (aka “button”) in the center of the case.
        • Move your hand forward, depressing the circle with said finger until you hear and feel a click.
        • Remove finger from button.
      2. Wait
        • Wait until the screen in front of you has finished turnng on
        • Continue to wait until there are little pictures on the screen.
      3. Open “Eye Dee Ten Tee” program
        • Find the picture (aka “icon”) on the screen in front of you that says “Eye Dee Ten Tee” (this would be a good place for a screenshot)
        • Move the mouse to the picture you found in the previous step.
          • (more inane steps here on how to move the mouse, what is a mouse, etc.)
        • Press the button on the mouse to begin using the said program
          • (more inane steps here on how to click a mouse?)
        • Wait until you see a blank white area on the screen with text at the top saying “ID10T” with a blinking cursor below that text.
      4. Type your text
        • Move your hands to the keyboard so your left index finger rests on the “F” key and your right index finger rests on the “J” key
        • Make sure your other fingers rest on the keys they naturally line up with in this position.
        • Move your fingers so one finger at a time depresses the key corresponding to the next letter in succession of the word(s) you desire to display on the screen.
      5. Print the text
        • (lots more steps here to print the text so the user doesn’t have to save the document somewhere that they would forget anyway becuase you haven’t explained directory structures yet)
    • More high-level steps here

I could continue ad nauseum, but I hope you get the idea already, and I think I’ve had way too much fun with my little demonstration exercise :-D Basically, more advanced users use the numbered steps and ignore the substeps, while novices can go at a slower pace with the detailed steps. And the occasional advanced user can refer to the detailed instructions when they get lost. Note the use of bold style and font sizes (i reserved italics for editorial comments, in this case) to visually separate the varying levels of steps to make this easier. Also note the lack of visual aids becuase I’ve already spent way too much time making this silly example to bother with graphics.

(Disclaimer: My instructions above are not complete and there are several obvious glaring holes where more steps need to be added to remain consistent with the level of detail provided. But unless I can get credit for this as my manual, it’s not worth the time nor the effort!)

(Warning: The above instructions are for entertainment purposes only and I disclaim any and all liability arising from the use or misuse of the above instructions regardless of the intentions of the user, or the orientation of the moon in relation to the earth and sun.)

(Warning: This example also serves as an example of a procrastination technique for avoiding credit-bearing projects. Doing the same is not recommended. You should really do the school work itself and turn it in early. But IANAL (I Am Not A Lawyer) and you should consult your own and not consider this a legal opinion in any way, shape, form, or point of fact.)