Creating User-friendly Documentation

By Neeraj Bhatia

We often hear that users do not read documents. To lure readers into reading our documents, we must make documents user-friendly.

Interpreting the term literally, a user-friendly document should be able to befriend a user. Some experts go to the extent of suggesting that documents should seduce users. We need not go so far; we can leave that task to our friends who write copy in advertising agencies.

User Focus

To befriend your users, you must get to know your users, their demographics, and their expectations from your documents. The better you understand your users, the more you can think like them and anticipate their needs.  

Respect your user

Do not make assumptions about your users. We are often told to assume users know nothing. This may not apply in all situations.

Speak to your user

Address one person, not a group. Write in the second person and use the present tense.

So, instead of saying “users must perform these tasks,” say “you must perform these tasks.”

We’ve heard a lot about why we should use the active voice. Here’s an example, though slightly far-fetched, that demonstrates how changing the voice can actually change the meaning of the sentence.

Passive Voice

If you are determined to have a disability, you will be paid the disabilities allowance.

Active Voice

If we determine that you have a disability, we will pay you the disabilities allowance.

Step into the user’s shoes

To think like a user, you must behave like one. Insist on using the application that you are documenting. Unless you use the product yourself, you cannot anticipate the problems that users might experience.

Speak the user’s language

You might need to learn the user’s language in order to speak it. For example, if you are writing for a banking application, learn about debits, credits, and all the jargon that bankers use.

Help the user understand your language

Introduce your user to the styles and conventions used in your document. Include appendixes and glossaries to explain new terms and concepts introduced in the document.

Task Orientation

Users read documents because they believe documents help them achieve their tasks. Your document must help users perform their tasks in an efficient manner.

Separate conceptual information from procedural information

Imagine a user following instructions to configure an application. In between sets of instructions, the user comes across a section on how and why a particular module was designed. Not only does this break the user’s flow of thought, but it also makes the user flip through pages to find the next set of instructions. This is distracting and annoying, to say the least. This is quite similar to what we experience when a commercial interrupts a particularly gripping scene in a movie.

If your users do need to have such conceptual information, present it in a way that is non-obtrusive and does not interfere with the flow of instructions.

Focus on tasks and not on tools

Users scan through your TOC and index to look for information on how to perform tasks. They usually do not look for names of tools or dialog boxes that help them accomplish tasks.

Keep your headings and index entries task oriented. Say how to do things rather than how to use a tool to do a thing.

For a section describing how to generate reports using the XReports feature, the heading “Creating Reports” is better than “Using XReports.”

Ease of Use

Advertisements for home loans from private sector banks highlight easy documentation. Surely, this factor contributes to why public sector banks, with their complex documentation requirements, are losing out in the home loans business.

Make your documents easy to use.

Users do not want to make their already complex lives more difficult.

Include correct, truthful, and current information

Make sure that all information in your document is accurate and current. Verify procedures by running through them yourself.

Keep all your screenshots up to date. Make sure that the screen titles, field names, and all other GUI objects are correctly referenced in your document.  It would be extremely annoying to a user to not find the “Identification No.” field as mentioned in your document because the engineers changed it to “User ID” in the GUI.

User interfaces keep evolving and you must update your documents accordingly. Do not depend on engineers to inform you of every small change they make. It is a good idea to keep an eye on changes reported through your source control tools.

Include all information that is necessary, but no more

We often face a dilemma on how much information to include in a document. Engineers often insist on describing the architecture or technologies used in the product. Most users would not care about whether you use “three-tier client-server architecture combined with MFC-based technologies that talk to Java servlets” or how clever your solution is. Users need to know how best to perform their tasks, so give users what they need, not what engineers think users need.

This is not to say that you should not provide conceptual information at all. Just be judicious about the context in which the information appears and whether it actually helps your users in that context.

If your document references procedures from another document, it might be a good idea to include those procedures in your document too. Users will find it extremely irritating to jump across documents to accomplish one task.

Ease of Understanding

If users experience difficulty in understanding the information presented in your document, they will avoid using the document. 

KISS (Keep It Simple and Short)

Present information in a way that users understand it the first time they read it. Remember that you are writing to provide specific information and not to impress readers with your knowledge or language skills. Desist from using overtly technical terms and avoid the tendency to use difficult words.

Keep your sentences and paragraphs short. Ensure that one paragraph represents one idea, even if it just a one sentence paragraph.

The probability of someone reading something is inversely proportional to the cube of its length. - The Writer’s Pocket Almanac, R. John Brockmann and William Horton  

Be consistent

Follow correct and appropriate writing conventions and word choices.

For example, some documents I’ve come across use the words computer, host, system, node, and server to mean the same thing. These terms could mean different things in different contexts, but when used interchangeably, they serve only to confuse users.

If your organisation does not have a style guide, follow another style guide that suits your requirements.

Organise information logically

The order in which information is presented must match the order in which information is used. If a user is expected to configure module A before using module B, describe module A before module B in your document.

Help users understand better

When giving an overview of a chapter or a procedure, describe what’s in it for the user. Describe the purpose of the section and what the user will achieve after reading the section.

Include appropriate examples, scenarios, analogies, and graphics to substantiate the information presented in the document. Analogies that users can relate to go a long way in explaining complex scenarios. Graphics, even when they contain only text (as in flowcharts), often work better than paragraphs of text.

When taking screenshots, go through the procedure yourself. Seeing actual values in screenshots will reassure that users that they are on the right track.

Ease of Finding Information

No matter what we would like to believe, most users do not read documents cover-to-cover. They read documents only when they need some information. It is only natural that we make it easy for them to find the required information.

Use visual elements to enhance the meaning of information

A lot of readers skim through documents before looking at specific information. A good page layout will enable users to identify important and relevant sections in the document.

Use sufficient white space. Trying to squeeze in a lot of information per page does not help users.

Leave ample space above and below headings to emphasise their relative importance. Highlight warnings and hints by putting them in a different font style or by adding a border around them.

Use graphics, vertical lists, and tables wherever appropriate. They improve readability by adding variety and interest to your document. Explicit lists make alternatives, steps, and separate items clear and distinct.

Use information retrieval tools effectively

Include all tools required help users retrieve the information they want. Focus on your TOC and index; these serve as good information retrieval tools, along with headers and footers.

Organise your contents in a way that gives users a good idea of what your document covers. Keep your TOC task-oriented.

In your index, include users' own terminology as well as system terms, terms from international standards, and those used by competitors.

For example, when indexing an application that uses a database, expert users might find the following index key useful.

database, querying 

But if your users are not database users, it might help to include terms that your users would understand.

data, accessing

data, retrieving

In Conclusion

Users are constantly learning more. Their comfort-level with technology is increasing. What was complex yesterday is easy today. The modes of communicating with users are changing.

In a world that is changing constantly, there can be no permanent solutions. Any set of guidelines to create user-friendly documents cannot work forever; they must keep evolving, constantly adapting to changing requirements.

(Neeraj is a Technical Writer with VERITAS Software. He is also the Competitions Manager of STC India. You can contact him at neeraj@stc-india.org.)

STC India | Home | Contact Us

Copyright © 2002 India Chapter STC. All rights reserved.