Let me show you the ways…August 25, 2010
Software applications, whether computer- or web-based, typically have several methods you can use to accomplish the same task. If you need to save your work, for example, you might be able to do any of these — or more — to perform that function:
- Click a toolbar icon
- Select an item from a menu path
- Click a command button
- Right-click and select an option from the shortcut menu
- Press one or more keys
- Plus any variations of these for mobile and small form factor devices, such as iPads.
So, when you’re documenting an application, how do you deal with all these options?
- Do you pick one method and stick to it throughout?
- Do you list every possible method?
- Do you mix them up?
My preferred method is to pick one and stick to it. For installed software, I tend to describe the menu path. Occasionally, I might also list the key combination in parentheses after the menu path; for example, ‘Select File > Save from the menu (or press Ctrl+S).’
I also think it’s important that the reader knows there are alternative methods they can use. So I might include a statement in one of my ‘About this Help’ topics similar to that below:
Often, there is more than one way to perform a function. For example, you may be able to use the menu, use a toolbar or toolbox button, right-click on an item and select from the shortcut menu that pops up, click on a unique button, or use a combination of keystrokes. Throughout this manual we have tried to show only one way of performing the function – usually the quickest way. However, you can use any one of the other methods. We have not documented all methods that you can use for a single function – this is to prevent confusion and ‘information overload’.
However, the problem with such a statement is that it may never be read as it’s hidden away in the Help, and not shown at the ‘point of need’.
What do you do? I’d really like to hear your opinion on this as I believe it’s an issue that faces technical writers every time we have a new application to document, and I don’t believe that there’s a single ‘right’ answer.