Dallas-Fort-Worth (DFW) Texas based Brandfocal provides Technical Writing services.
Most technical writers spend at least part of their time writing procedures. Procedures are essentially detailed instructions for performing one or more tasks. Unless your documentation is strictly conceptual (explaining a topic rather than telling your readers how to use the software), you will need to write procedures. Since readers will be following your instructions on real applications with real data, it is particularly important that your directions be clear, concise, accurate, and easy to follow.
Use active language
A procedure tells your reader to perform a specific action or set of actions. Good instructions use active language, commanding the reader to act rather than discussing actions that have been taken or could be taken by others. There’s a big difference between saying “the dropdown box in the corner of the page can be used to select the date” and “select a date using the dropdown box in the corner”. The first informs your reader what that particular dropdown box does and the second tells them to do it. The text introducing a procedure can discuss when to perform the procedure; the procedure itself needs to tell the user how to do the needed actions and assume that they are, in fact, doing them.
Use short phrases and sentences
It’s important to give each instruction as clearly as possible. The fewer words used to convey a particular task, the less places there are for a user to get confused. Anyplace you can use a single word to convey an action, do so.
Avoid any elaboration or explanation within the procedure itself. If you need to provide options or explain why a particular task is important, do it in paragraph form before you begin the procedure. If the user can choose more than one way to perform a specific task, present each procedure separately after explanatory text discussing when that particular option is a good choice.
Use ordered lists
By definition, a procedure consists of a set of tasks that need to be performed in a specific order. By presenting these tasks in an ordered list, with steps 1, 2, 3, etc., you reinforce the need to follow a set order. Numbered lists have an ingrained implied order that’s almost subconscious and thus provide much stronger impetus that simply supplying paragraphs filled with “Do this then do that” terminology.
Ordered lists also help you bone down the language to its simplest, and thus clearest, form. By removing all of the extraneous connective words needed to indicate order in paragraph form you remove verbiage that could confuse your readers.
Provide one instruction per step
One of the common mistakes people make when writing procedures is trying to stuff several steps into one line. They think that each instruction is simple so they can safely combine a few easy directions into one combined step. Unfortunately, no matter how simple those individual instructions are, any step that tells you how to do more than one thing is potentially confusing. Avoid that confusion by limiting each step to one instruction no matter how simple or mundane.
For instance, when telling users how to create a new account you could say:
- Enter the desired username and password into the appropriate fields
- Select the desired permissions for the new user
- Hit enter to add the user
but this is clearer:
- Enter the desired username in the username field
- Enter the desired password in the password field
- Select the Read checkbox if this user has read privileges
- Select the Write checkbox if this user has write privileges
- Select the Exec checkbox if this user has execute privileges
- Hit enter to add the user
Be consistent
Consistency is important in all documentation, but especially so when writing procedures. In particular, it is paramount to use consistent names for screen elements like buttons, forms, tabs, and windows. Many of these elements won’t be named within the software so you’ll have to name them. Choose a logical name that makes it obvious what particular element you are referring to and then propagate that name throughout the entire documentation set.
Collect all of the names you create and make sure they’re added to a common database of product terminology. In an ideal world, these terms would be added to a group style guide or glossary, but even if you don’t do that, make sure they are preserved and available to everyone working on that product.
Don’t feel like you need to come up with ten creative ways to tell people how to press a button. Tell them to press the button (or tap it, or choose it, or whatever terminology you’ve decided on) each and every time. You shouldn’t break out the thesaurus, but rather use repetitiveness to really pound home clarity.
In addition to consistent use of names and terminology in general, it’s also important to use parallel constructs within your procedures. The human brain looks for parallelism and is bothered when it’s not there (even if it doesn’t completely understand what’s wrong with a particular sentence). By beginning each step with a similar phrase and tone, you’re allowing the user to ignore the writing and concentrate on the content.
Perform the acts you’re describing
A sure way to provide incorrect instructions is to rely on your memory when writing procedures. Even if you’ve performed a task hundreds of times, you will always forget one small step or provide wishy-washy directions at some point along the way because you can’t quite remember if the menu item is named “Remove all users” or “Delete users”.
If you’re overly familiar with a procedure you are also prone to leave out steps or combine multiple steps into one gigantic step that’s confusing to someone not as familiar with the process as you are.
For instance, most of us know how to save a file. Let’s assume you’re all using Mac OS X Jaguar writing in TextEdit (since that’s precisely what I’m doing right now and I always heed my own advice of doing what I’m describing). I could assume you understand the basic idea of how to save a file and provide this procedure for saving files:
- Save the text file in the location of your choice
But in reality what I want you to do is:
- Select the File|Save As menu item
- Name the file in the Save As text area
- Select a location from the Where dropdown box
- Press the Save button
or alternately:
- Select the File|Save As menu item
- Name the file in the Save As text area
- Navigate to the location of your choice using the directory viewer
- Press the Save button
Now, most of that should be self-explanatory, even if you’ve never saved a file in Jaguar before. But people learn and extrapolate at different rates and by spelling out precise directions I’ve made sure every reader will be able to follow my instructions quickly and without much experimentation.
Summary
There’s no question that the ability to write clear and correct procedures is absolutely paramount for anyone writing software documentation. It’s also true that there are a lot of rules. The good news is that most of us have a lot of practice with procedures. We may not call them procedures, but we encounter sets of instructions all of the time in daily life in everything from recipes when we cook to driving directions when we travel. Thus we all have an inborn recognition of procedures and an inherent understanding of how they work. You just need to add common sense and good writing skills to that understanding and you’ll be able to write your own clear and easy to follow procedures.