Lesson 4: Writing Procedures
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're referring to and then propogate 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.
