Labels and other dogs

Here I am, in my basement, surrounded by mountains of dog food I'm desperately trying to organize. We own one dog, an odd-looking labradoodle named Jessie, however, my brother-in-law's dog Gracie often visits. Both dogs need feeding, therefore I own two large plastic containers filled with food for each dog, and both dog food types look almost identical. I wonder: What is the best way to label each container?

The obvious labels would be Jessie and Gracie, however I often get the dogs' names mixed up even when I'm around them; Jessie and Gracie simply sound too similar, and the dogs themselves do not carry signs that clearly identify them. I decide on the labels Our dog and David's dog, eliminating all confusion.

Labels are everywhere in documentation, specifically in:

• the name of a document: User Guide, Admin Guide, Install Guide, and so on
• chapter names
• heading titles

These are all critical identifiers, and just like the dog food box labels, they need to be clear, descriptive, as short as possible, and leave no room for confusion.

As an example, our company used to create Installation Guides, but this was not descriptive enough because it did not distinguish between guides for users who were installing our software for the first time, and guides for users who were upgrading an existing version. We therefore changed the document titles to:

• Guide for New Installations
• Upgrade Guide

Chapter titles and headings also need to be clear and unambiguous. Documents is vague, Creating Documents is better, and Creating Documents on a Database may be better still, especially if you need to distinguish between this topic and creating documents in another location.

Labels are also in software in the form of fields, menus and title bars. Experienced technical communicators provide valuable feedback and insight for the naming of these items. As with documentation labels, software labels need to be clear, consistent and leave no room for confusion.

I'll share an interesting example.

I was working with a developer on a complex database administration application. One of the functions the user could do was rerun a query by clicking a button labeled, appropriately enough, Rerun query. The developer said the problem was that there were many different queries that the user could run, and that they needed a quick way to know which one they had run before re-running it. I asked if was possible to embed the name of the query that had just run into the button name, so that, for example, if the user had run the Last Name query, the button label would be Rerun Last Name query?

I remember the developer's eyes widening and his face lighting up as recognized the elegant beauty of this solution. "Yes," he said, "it can be done!"

More exotic things I have be asked to label include database tables, attributes and elements. It can be very challenging, and very rewarding to give these things the right name, one that nearly sums up the essence of what the thing is. So choose your labels carefully - they can turn good documentation into great.

Now excuse me while I go feed the dogs...