Questions to ask when writing procedures

Who is your reader?

A sense of audience is important. If the audience are neophytes to your discourse community, then you need to remember that. Plan for it. Explain words that you might think are elementary. (Just last week, when discussing blogging, I had a student ask what a post was. I had assumed they all knew.)

Even if the audience isn’t new to the discussion, perhaps they don’t understand the terminology. They might even think they understand the terminology when they don’t. (NASA engineers wrote management and said that the secondary o-rings failed catastrophically at such-and-such point. The management didn’t think too much about that. Secondary, after all, means back up. So they didn’t fix the problem. And The Challenger blew up. Because secondary doesn’t mean back up to aeronautical engineers. It means second.)

What is their experience with the product? How will they be using the product? 

It may seem strange to think of a gym as a product, but if you are creating a New User’s Guide to X Gym, then the gym is the product. Right away, your title gives you an awareness of their experience level. It’s low.

Everyone who is new to the gym will need some basic information (such as hours of operation and what facilities are available). You might also provide general information that is useful to anyone, but is not usually available (such as the busiest hours).

Having users who are new to a particular gym does not necessarily mean that they are new to gyms in general. You want to provide information that is useful to newbies at the whole gym experience (such as a discussion of the differences between free weights and weight machines). And you want to provide information that will be useful to those who are experts in gyms, body builders or aerobics instructors, but are new to your particular gym (such as what kind of equipment the gym has, by manufacturer, or how often Zumba classes are offered).

How can you make the information most accessible?

Think headings. Give precise informative headings. This helps the reader skim quickly and efficiently.

Make them short, so they are easy to read, but not so short that they are useless.

Make them stand out, usually by bolding, so they are easy to see and to find, when flipping through your guide or manual.

Think paragraphs. I am writing this post in paragraphs. But many people don’t read paragraphs well. Perhaps they aren’t comfortable reading, perhaps they think it takes too long, or perhaps they are visual learners. Whatever the reason, many people don’t read paragraphs well. Even those who do, sometimes find paragraphs hard to read because they are dense. So what can you do to make the information more accessible in a paragraph?

Use block-style paragraphs, which are short. They get the information across. And multiple ideas don’t get lost in a long paragraph.

Use both headings and subheadings. (See as an example the questions and the “think” declarations in this post.)

Think lists. You can write the information in lists. You can number these, if something happens to need to be done in a particular order. Or you can put the list in bullets, if there is no necessary order.

This can be done well (such as in Dr. Clark’s bullet points under “Evaluation” on the assignment guide) or it can be done horribly (such as in an employee manual which said you should read and follow “these rules,” which included stealing, poor workmanship, and willful destruction of company property in its numbered list).

Think fonts. Serif (or footed) fonts, where the capital I and the lowercase l do not look the same, are more easily read. Large sizes of fonts (or perhaps I should say reasonably large sizes) help reading.

Italics are harder to read. Use them sparingly.

All capitals are also harder to read. And they now mean “I am yelling.” So avoid them.

Think color. Color draws attention to whatever is in color.

If you have a screen shot or a picture of how to do something, it is great if you can have it in color. People look at color. However, you can go too far with this. If everything in the text is a different color, the color no longer draws attention.

Also, you need to think of color if you are writing on the net. A black background with white letters may look cool (a blogging mathematician thought so and switched his blog to a theme with that), but it is hard to read. A bright blue background with yellow letters is even harder to read, but I’ve seen those, too. I don’t even bother trying to read sites like that.

Think graphics. Any graphics used are supposed to emphasize or clarify written content.

A screen shot of what should be on the computer at this stage is useful for technical manuals or guides to how to install or use software.

If you are discussing how to tie ties, pictures of how to tie a Windsor, an ascot, or the cross knot can be useful.

A diagram can be used instead of or in addition to a verbal description to explain a process, for example.

They are not usually included as decoration.

However, sometimes simple decoration can be good. My church puts the words to music up on huge screens at the sides of the auditorium. And they use a pretty background around the words. Why? It doesn’t add anything to the song “Here I am to worship” if there is a purple background with flowers growing out of the left side of the screen. But it is nicer to look at. And that is its job. The purple and the flowers are to make the screen nicer to look at. People love beauty. So they make the screen on which the words appear beautiful.

This entry was posted in Technical Writing: Dr. Davis. Bookmark the permalink.

6 Responses to Questions to ask when writing procedures

Leave a Reply

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