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.


  1. I’m with you. I stick with the standard menu paths. We have a section for keyboard shortcuts, so there’s one topic for those who like them. And if people discover the right-click context menus, good on them – I consider those menus a bonus rather than core functionality.

  2. Thanks Jenny. I forgot to add that I also have a topic just for the toolbar icons. Icon on the left, description on the right, perhaps with a link to a related topic (e.g. a Reports icon’s description would have a link to the top-level ‘Reports’ section in the Help).

  3. If there are enough application-specific icons to require an icon description table, and I’ve already captured pictures of the icons to put in the table, I just insert the icons in the text, like, “Click XX to whatever the icon does.” I use a graphics program (even MS Paint will do)to clean up each icon’s outline (or put a dark border on it), and reduce it as small as possible so it will fit into a text line.

    To insert the icon graphic into text, I put two spaces where I want to put the icon, and use Insert> Picture> From file to put the icon graphic between the two spaces. Then I select only the graphic, and use Format> Font> Character Spacing> Position: Lowered. The default for By: is 3pt. If it looks OK, that’s it. If it looks too low, I go back into the Character Spacing options to change the By: to 2pt.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: