Creating Quality Content

Why Bother?

There's no doubt about it: writing good documentation can be time-consuming and tedious. Sometimes you may wonder if it's even worth it because it seems like no one ever reads it. "They" will just call you for the answer anyway, right?

That may be true in some cases. Some people are more inclined to call or email for help rather than look for help on their own. But can you blame them? For years, help menus and files were plain sad. If they had any substance it was often more cryptic than the problem you needed to solve.

Fortunately this trend has changed over the years and more people are at least willing to give help files a try. The key to keeping your audience's attention is to make it worth their while. Remember, in the end, the more useful your documentation is for your audience, the less time you spend answering the same questions.

Below are suggestions and tips for making the most out of your documentation:

 

TITLES

Titles for help topics are like well-placed road signs. If the title is misleading or confusing, the document will have no value because your audience won't look at it. Give your topics or file names titles that tell the user what they'll learn or the problem they'll solve. An exception may be if your audience is aware of different solutions to the same problem.

Consider these two title options for the same material:

  • Instructions for Form Based Extract Bill and XML Publisher
  • Printing Student Bills

The second title is more successful because it doesn't expect the user to know the process or tools needed to print student bills. Even if a user knows the terms "form based extract bill" and "XML publisher," they know they're looking for information on printing student bills. Whereas the novice user might not know those terms and would be frustrated when looking for help.

 

SPEAK TO YOUR AUDIENCE

One challenge with writing documentation is writing for your audience. Most likely you are a subject matter expert on the topic you are documenting. Yet you're often writing for a novice. This requires more detail than writing for an advanced user. For a novice, you should assume they know nothing; you cannot skip any steps, no matter how trivial or second nature they seem to you. When writing for an advanced user, you might be able to leave some details out. For example, if you're writing instructions to register for a class, you'll need to tell the student how to navigate to the class registration screen.

 

TIPS:

  • When you indicate to click on something, make sure the user knows how to get to that link or screen.
  • Avoid jargon, acronyms, or process names that aren't known to your audience.
  • Ask someone else to review your work. The best test would be to ask someone who fits into your targeted audience.

 

OTHER SUGGESTIONS FOR BETTER DOCUMENTATION

  • Make sure your actions and directions match the screen shot.
  • When directing your reader to a menu or location, give them the location first then the action. For example, write: Select the File menu and choose Save. Though it's a minor change, this is easier to follow than "Choose Save from the File menu."
  • Be consistent with your actions. Click means single left right. Double click means double left click. Right click means a single right click.
  • Avoid acronyms unless your audience is more familiar with the acronym than the phrase it describes.