Jerz's weblog -- instructions: how to write guides for busy, grouchy people

Put the Lime in the Cocoanut. Elena’s Pantry, used with permission.

Instructions: How to Write Guides for Busy, Grouchy People Jerz > Writing > Technical & Professional >

People hate reading instructions, and will only glance at them when they are hopelessly lost. By then, they will already be frustrated and behind schedule. For this reason, you should organize your instructions carefully, phrase them clearly, and make them as brief as you possibly can.

This document introduces five basic principles about writing instructions. Any professional writing textbook will have a long section on writing instructions and manuals, but the basics are as follows:

1. Know your audience. 2. Provide a brief introduction. 3. Write each step as a command. 4. Use numbers for commands, bullets for options. 5. Plan to test and revise.

1. Know your audience. Most college assignments are written for an ideal reader — an expert whose job includes scrutinizing and pondering everything that you write.

Don’t expect your audience to read your document as carefully as you or your English teacher would. People in the real world read instructions when they are impatient, fatigued, or even terrified.

Your writing must be clear enough that readers can understand with minimal effort. This does not mean using baby language or avoiding complex details; it does mean using vocabulary appropriate to your audience, and including details that your readers need to perform the immediate task. (How do you know whether you have included enough detail? Conduct a usability test.)

2. Provide a brief introduction. Help your readers determine, even before opening the brochure or downloading the web page, whether this document will help them do whatever it is they want to do.

State in plain language, what task your document describes: “Installing and Operating the Canon BJ-200ex Bubble Jet Printer.”

In a few sentences, state the purpose of the document; who should read it, and under what circumstances? If it will help your reader, you might also explain what your document does not do.

If you wish, you may place extended background information in a subordinate position (a marginal note, a sidebar, or a completely different document) that does not interfere with the user’s access to the list of required actions.

Note: Technical support documents are no place for marketing slogans — the reader has already got the product, and is probably annoyed with it at the moment.

3. Write each step as a command. Use the the imperative mood — that is, phrase each step as if your reader has just asked, “What should I do next?” Answer by giving a direct command: “Add two cups of flour.”

“Tab A should be inserted into slot B.”

Jerz's Literacy WeblogJerz Culture Ethics Humanities Journalism Literature Media Writing Teaching About

Practically speaking, most users will skip the introduction and go right to the first numbered step. (Don’t put anything vital in the intro!)“

http://www.flickr.com/photos/elanaspantry/4519426688/in/photostream/
http://www.flickr.com/photos/elanaspantry/4519426688/in/photostream/
http://jerz.setonhill.edu/
http://jerz.setonhill.edu/writing/
http://jerz.setonhill.edu/writing/technical/
http://jerz.setonhill.edu/writing/technical-writing/instructions-how-to-write-for-busy-grouchy-people/#audience
http://jerz.setonhill.edu/writing/technical-writing/instructions-how-to-write-for-busy-grouchy-people/#introduction
http://jerz.setonhill.edu/writing/technical-writing/instructions-how-to-write-for-busy-grouchy-people/#command
http://jerz.setonhill.edu/writing/technical-writing/instructions-how-to-write-for-busy-grouchy-people/#numbers
http://jerz.setonhill.edu/writing/technical-writing/instructions-how-to-write-for-busy-grouchy-people/#Test
http://jerz.setonhill.edu/writing/technical-writing/usability-testing/
https://jerz.setonhill.edu/
http://jerz.setonhill.edu/
https://jerz.setonhill.edu/culture/
https://jerz.setonhill.edu/ethics/
https://jerz.setonhill.edu/humanities/
https://jerz.setonhill.edu/journalism/
https://jerz.setonhill.edu/literature/
https://jerz.setonhill.edu/media/
http://jerz.setonhill.edu/writing_/
https://jerz.setonhill.edu/teaching1/
http://jerz.setonhill.edu/about/contact/
A reader consults a set of instructions in order to find out what actions to perform, but this phrasing de- emphasizes the action.Who or what is supposed to insert the tab? Is this a value statement, akin to “The world’s precious resources should be conserved”? One might agree with that assertion, but still have no idea how to go about performing the action of conserving. For this reason, commands should employ the active voice.

“Insert tab A into slot B.”

This revision begins with a verb that specifies what action the reader is supposed to perform.

Note: most readers will skip the introduction and start reading at the first numbered step. If your user will have to know a lot of background information before beginning, put the vital information into the form of a checklist, rather than a long, discursive essay.

When you are describing steps that must be completed in a certain order, common sense insists that you start with the first step. (You would be surprised to learn how many of my students describe steps out of order.) Number each step, in order to emphasize the sequence.

Steps for a specific task, which must be completed in a specific order. (These items are arranged in strict chronological order.)

A general essay, offering options and possibilities. (The text below is not a set of instructions. The items are not arranged chronologically; they are general tips, rather than specific commands.)

How to “Do the Hokey Pokey” The “Hokey Pokey” is a simple dance that helps teach toddlers the parts of the body. It also helps tire youngsters out.

In order to perform the “Hokey Pokey” dance, do the following:

1. Stand in a circle. 2. Sing the following words, performing the actions

described. 1. “You put your right hand in.”

(Put your right hand into the center of the circle.) 2. “You put your right hand out.”

(Let your right hand fall to your side, or hold it away from the center of the circle.)

How to entertain your toddler In order to spend quality time with your toddler, do the following:

Consider your child’s developmental stage. Determine what mood he or she seems to be in at the moment. Pay close attention to what your child does and doesn’t like. Remember is that children imitate everything they see.

Consider your child’s developmental stage

A youngster who is just learning to walk may be frustrated by the “Hokey Pokey” dance (which requires children to stand on one foot part of the time). But if you play the game on a nice soft rug, and if you don’t mind falling down yourself in order to keep your child company, then the “Hokey Pokey” dance can still be fun. Before you know it, your toddler will be able to perform all the steps without any help.

Note: when you are providing a list of possibilities, which do not have to come in any particular order, use bullets instead of numbers.“

Warning: encouraging your toddler to perform this dance just before naptime may cause the child to become excited or cranky.“

http://jerz.setonhill.edu/writing/grammar/act-pass.htm
3. “You put your right hand in.” (Put your right hand back into the circle.)

4. “And you shake it all about.” (Shake your right hand vigorously.)

5. “You do the Hokey Pokey and you turn yourself around.” (Point your fingers towards the ceiling, and alternate moving your hands up and down, while turning in place, until you are facing the center of the circle again.)

6. “That’s what it’s all about!” (Giggle, clap, or otherwise communicate to your toddler the idea that the dance is fun.)

3. Repeat step 2, substituting “right hand” with other terms (such as “left hand”, “right foot,” “left foot,” “head”, and “whole self”) as desired.

There is no specific end to this song. Continue as long as you wish.

Determine what mood your toddler seems to be in at the moment

Most toddlers are so interested in their surroundings that they have trouble focusing on one thing for very long. If you are dead set on reading the literary classics to your toddler, but he or she keeps grabbing the book out of your hand and making up stories to go along with the pictures, don’t punish your toddler by insisting on finishing the story. When children get a little older, they get interested in complex stories again; but for the time being, just sit back and watch your child’s imagination blossom.

Pay close attention to what your child does and doesn’t like.

[details here]

Remember that children imitate everything they see.

[details here]

4. Use numbers for commands, bullets for options. Since some readers will only need help for one section of a larger operation, divide up your instructions according to discrete subtasks. If you want your reader to perform tasks in a specific sequence, number the steps. If you want your reader to choose from among a list of options, bullet the options (otherwise the reader won’t know when to stop). Write brief introductions to each section, to clarify whether a list of steps is supposed to be sequential or optional.

Hint: If your objective for performing the “Hokey Pokey” is to tire out your toddler instead of yourself, you may omit the action of turning in a small circle at step 2.v. As long as the toddler knows to turn around at that point, you can just stand still and watch your little maniac burn off some energy.

“

Making A Lime and Coconut Drink

These instructions describe how to make one serving of the beverage described in the “Lime in the Coconut” song. It also explains what to do if the drink makes you sick, and suggests ways you might try to get the annoying tune out of your head.

You will need one (1) lime and one (1) coconut.

I. Preparing the Drink

1. Take lime. 2. Take coconut. 3. Put the lime in the coconut.

“

5. Plan to Test and Revise. Instead of investing your resources into polishing your first draft, create a prototype and conduct usability testing on it. You’ll be surprised at how much you can learn.

1. As closely as is practical, simulate the environment in which you intend your audience to follow your instructions. 2. Find a volunteer who represents the intended audience, and ask him or her to follow your instructions. 3. Keep quiet and take careful note of any problems. 4. Revise your document, and then try again with another volunteer. 5. Repeat until you are satisfied with the results.

For larger, more complex projects, use five test subjects for each trial run. See:Usability Testing.

See also: MLA Style: Using MS-Word to Format a Paper (example of detailed instructions)

Dennis G. Jerz

28 Apr, 2000 — first posted 23 May, 2000 — minor edits 10 Nov, 2002 — minor update 16 July, 2011 — refreshed and tweaked

4. Drink it right up.

II. If You Get Sick

Drinking the lime and the coconut may result in indigestion. In case of a bellyache, do the following:

1. Call the doctor. 2. Wake him up, if necessary. 3. Say, “Doctor! Is there nothing I can take, I say Doctor! To relieve this belly ache!”

III. Suggestions for Getting the Tune Out of Your Head

You might try any or all of the following. Repeat as necessary, until the ringing in your ears drowns out the song, or until you lose consciousness.

Hit yourself on the head with the coconut, or Listen to a Britney Spears album, or Dwell in misery upon your misguided, sinful life.

http://jerz.setonhill.edu/design/usability/prototype.htm
http://jerz.setonhill.edu/design/usability/intro.htm
http://jerz.setonhill.edu/design/usability/intro.htm
http://jerz.setonhill.edu/writing/academic/mla_style.html
29 thoughts on “Instructions: How to Write Guides for Busy, Grouchy People”

Pingback: Due Date #2, Due: Wed. 8/31/11 (11:59pm, PST) « TWC301 Course Blog

Logan Schneider 10 Oct 2011 at 1:14 pm

Writing guidelines is usually the easiest and fastest thing to write. Writing instructions has to be very precise and exact.

http://rodrigotwc301.wordpress.com/2011/05/31/due-date-2-due-sat-6411-1159pm-pst/
Reply

Dennis G. Jerz 10 Oct 2011 at 7:05 pm

Good point. Just in case the subtitle of this document might give the impression that instructions and guidelines are interchangeable, I’ll second what you wrote, Logan.

Reply

lizzy kleyn 12 Oct 2011 at 11:25 am

this was great(:

Reply

dj kleve 14 Oct 2011 at 1:58 pm

wow lizzy

Reply

travs 12 Oct 2011 at 11:27 am

Hey Mrs. buckley hi!

Reply

dylan 14 Oct 2011 at 2:01 pm

language is kinda fun that y we should have more fun stuff

Reply

Jan Caulfield 2 Mar 2012 at 7:34 pm

May I please I use this example of writing instructions for a technical writing course I teach in for Harrisburg University?

http://jerz@setonhill.edu/
http://jerz.setonhill.edu/writing/technical-writing/instructions-how-to-write-for-busy-grouchy-people/
http://delicious.com/buckleyke
https://jerz.setonhill.edu/writing/technical-writing/instructions-how-to-write-for-busy-grouchy-people/?replytocom=52784#respond
https://jerz.setonhill.edu/writing/technical-writing/instructions-how-to-write-for-busy-grouchy-people/?replytocom=52888#respond
https://jerz.setonhill.edu/writing/technical-writing/instructions-how-to-write-for-busy-grouchy-people/?replytocom=53601#respond
https://jerz.setonhill.edu/writing/technical-writing/instructions-how-to-write-for-busy-grouchy-people/?replytocom=54486#respond
https://jerz.setonhill.edu/writing/technical-writing/instructions-how-to-write-for-busy-grouchy-people/?replytocom=53603#respond
https://jerz.setonhill.edu/writing/technical-writing/instructions-how-to-write-for-busy-grouchy-people/?replytocom=54489#respond
Reply

Dennis G. Jerz 2 Mar 2012 at 7:51 pm

As long as you cite it, be my guest.

Reply Pingback: Bedford Bits: Ideas for Teaching Composition » Blog Archive » Teaching about Writing Instructions with Comics

Teri Stearns 27 Aug 2014 at 9:07 pm

I have shown this article to many people as a quick overview for technical writing, and it’s been a wonderful resource. I can’t thank you enough for this!

Reply

Dennis G. Jerz 27 Aug 2014 at 10:28 pm

Thanks for letting me know you found it useful.

Reply Pingback: Instructions | Technical Writing

Kate 13 Apr 2015 at 2:11 pm

I love your directions for making the Lime and Coconut Drink. Thank you for the giggle!

Reply

jevoninyocup 17 Apr 2015 at 2:26 pm

This is going to help me greatly in a couple hours: http://t.co/dW0VPDA1n5 #writing #sprint #notthephones

Reply

Richard Antoine 28 Jul 2015 at 11:08 am

http://jerz@setonhill.edu/
http://jerz.setonhill.edu/
https://twitter.com/jevoninyocup
https://jerz.setonhill.edu/writing/technical-writing/instructions-how-to-write-for-busy-grouchy-people/?replytocom=186296#respond
https://jerz.setonhill.edu/writing/technical-writing/instructions-how-to-write-for-busy-grouchy-people/?replytocom=186349#respond
http://blogs.bedfordstmartins.com/bits/elizabeth-losh/teaching-about-writing-instructions-with-comics/loshalex/
https://jerz.setonhill.edu/writing/technical-writing/instructions-how-to-write-for-busy-grouchy-people/?replytocom=478723#respond
https://jerz.setonhill.edu/writing/technical-writing/instructions-how-to-write-for-busy-grouchy-people/?replytocom=478729#respond
http://burristechwriting.wordpress.com/2014/11/11/instructions/
https://jerz.setonhill.edu/writing/technical-writing/instructions-how-to-write-for-busy-grouchy-people/?replytocom=528622#respond
http://t.co/dW0VPDA1n5
https://jerz.setonhill.edu/writing/technical-writing/instructions-how-to-write-for-busy-grouchy-people/?replytocom=528716#respond
Dennis, I agree with your points as they match my experience. I’m developing a training class and I’m trying to find quantitative research to reference that supports my observations. Do you know of any research studies that have tested reading comprehension of lists versus narratives/essays?

Reply

Dennis G. Jerz 28 Jul 2015 at 10:32 pm

http://www.nngroup.com/articles/how-users-read-on-the-web/

This is from 1997. I’m sure there are more recent studies, and I am sure there are studies that cover reading in general (this one covers online reading). I have not taught technical writing for some time, but here is a 2003 article that argues that bullet lists are shallow and make us dumber. http://www.units.miamioh.edu/technologyandhumanities/tuftebullets.htm

White papers, annual reports, vision statements, and other important big-picture documents really do need narrative, so I won’t say that bullet points are superior to narrative in all cases. In the case of online writing and the specific case of writing instructions, the context of the reading act means that putting your ideas into bullet points can often increase the chances that your readers will actually read what you write, but I’d say that most important things probably should be written as narrative first, for the small audience that really needs to know all the details, but for the general public or for people who only need to get the general idea, bullet points are ways that the writer can make best use of the limited attention that general audiences will give.

Reply Pingback: Writing Instructions That Lead to Action | DOUG TOFT

dougtoft 24 Aug 2015 at 7:17 am

How to write instructions for busy, grouchy people http://t.co/LTZ4hbImWP

Reply

tomas antonio 2 Dec 2015 at 10:12 am

well you see im in communications right now and this article kinda sucks you should update it

Reply

Dennis G. Jerz 2 Dec 2015 at 10:03 pm

Ironic post is ironic.

Reply

http://jerz.setonhill.edu/
https://twitter.com/dougtoft
http://jerz.setonhill.edu/
https://jerz.setonhill.edu/writing/technical-writing/instructions-how-to-write-for-busy-grouchy-people/?replytocom=532877#respond
http://www.nngroup.com/articles/how-users-read-on-the-web/
http://www.units.miamioh.edu/technologyandhumanities/tuftebullets.htm
https://jerz.setonhill.edu/writing/technical-writing/instructions-how-to-write-for-busy-grouchy-people/?replytocom=532890#respond
http://dougtoft.net/2015/08/18/writing-instructions-that-lead-to-action/
http://t.co/LTZ4hbImWP
https://jerz.setonhill.edu/writing/technical-writing/instructions-how-to-write-for-busy-grouchy-people/?replytocom=534316#respond
https://jerz.setonhill.edu/writing/technical-writing/instructions-how-to-write-for-busy-grouchy-people/?replytocom=540204#respond
https://jerz.setonhill.edu/writing/technical-writing/instructions-how-to-write-for-busy-grouchy-people/?replytocom=540224#respond
Carol Jacobson 5 Feb 2016 at 12:55 pm

For the past several semesters, I’ve used your article (credited, for sure) as supplementary reading for a class I teach at Missouri State University. Not only is it a fine example of well-written instructions, it’s also such a fun read…and acquaints my scholars with that fine musical classic “Lime in the Coconut.” Thank you for helping me show my students how much fun technical writing can be!

Reply

Dennis G. Jerz 5 Feb 2016 at 1:53 pm

Thanks so much for your kind note!

Reply

rkeithtaylor 19 Feb 2016 at 11:46 am

I use this in my ENGL 101 at IUP. It is very helpful for our informative sequence.

Reply

Pingback: How to Write a Good "How To" | Breaking Even Communications

Ms Ekah 23 Aug 2017 at 6:56 am

So simple and direct. No mess, no fuss, just do it instruction!

Reply

Pingback: umuc wrtg393 WA 2 Instruction Manual - StudyPool

Cole 14 Nov 2017 at 9:59 am

Stay Savage

Reply

Jason Savage 30 Nov 2017 at 1:03 am

http://jerz.setonhill.edu/
http://gravatar.com/rkeithtaylor
https://jerz.setonhill.edu/writing/technical-writing/instructions-how-to-write-for-busy-grouchy-people/?replytocom=541344#respond
https://jerz.setonhill.edu/writing/technical-writing/instructions-how-to-write-for-busy-grouchy-people/?replytocom=541345#respond
https://jerz.setonhill.edu/writing/technical-writing/instructions-how-to-write-for-busy-grouchy-people/?replytocom=541491#respond
http://breakingeveninc.com/how-to-write-a-good-how-to/
https://jerz.setonhill.edu/writing/technical-writing/instructions-how-to-write-for-busy-grouchy-people/?replytocom=571773#respond
https://www.studypool.us/umuc-wrtg393-wa-2-instruction-manual/
https://jerz.setonhill.edu/writing/technical-writing/instructions-how-to-write-for-busy-grouchy-people/?replytocom=579318#respond
This has been on the internet for 17 years and people are still posting on it. That’s pretty cool.

Reply

Leave a Reply Your email address will not be published. Required fields are marked *

Comment

Name *

Email *

Website

Notify me of new posts by email.

Post Comment

This site uses Akismet to reduce spam. Learn how your comment data is processed.

We use cookies to ensure that we give you the best experience on our website. If you continue to use this site we will assume that you are happy with it.

Ok

https://jerz.setonhill.edu/writing/technical-writing/instructions-how-to-write-for-busy-grouchy-people/?replytocom=580500#respond
https://akismet.com/privacy/