Ingredients of Good Documentation Summarized

Here is a quick recap of what I think are the 7 most important ingredients of good documentation:

• Logical flow of information
• Simple language
• Intelligent Content for the Intelligent User
• Judicious use of Screenshots
• Hierarchical Table of Contents
• Links
• Accurate Information

You can, of course, read a more detailed explanation of each of these points in my earlier posts.

Ingredients of Good Documentation #7

Accurate Information
The one reason why technical writing is considered different from creative writing is that as a technical writer you must not get “creative”. You have to write about what your product / service does and not what you would ideally have liked it to do.

• Make sure to provide technically accurate information.
• Watch out for grammatical errors. Always run a spelling and grammar check.
• Don’t gloss over known issues and bugs; not mentioning them is akin to misleading users.
• Provide notes wherever necessary to highlight important information. Caution notes must appear right at the beginning of the topic, preferably using a different font size and color to catch the readers’ attention.

Ingredients of Good Documentation #6

Links
Links are perhaps the single most important differentiator of online content. It’s, therefore, imperative that you make liberal use of them in your documentation. Use links to:

• Provide logical navigation to the reader. (Read Next, Related Links, Back, Home, etc.)
• Maintain focus on one topic and direct readers to relevant pages for associated information
• Keep your pages short and to-the-point
• Improve readability
• Break up complex content into smaller chunks
• Avoid repetition of content / steps explained in detail elsewhere in the document

Ingredients of Good Documentation #5

Hierarchical Table of Contents

After Search, the Table of Contents (TOC), is perhaps the one element of help manuals that is used most often by readers. The importance of a good TOC is, therefore, hard to overlook.

I have seen several user guides that have long TOCs. Almost every second topic makes its way to the top-level TOC. So why are many technical writers tempted to add as many topics as possible onto the first-level TOC? Here are some common reasons:

•  To (supposedly) make it easier for the reader to quickly find what they are looking for
• For want to complete understanding of the product / subject

The first line of reasoning is absolutely baseless. A long TOC only adds to the clutter. Why do all help authoring tools (like RoboHelp and Flare) support hierarchical TOCs? Simply because they are an important ingredient of good documentation!

This brings us to the second point. The work of a technical writer is not merely that of a writer. A technical writer must be a product expert and an end-user rolled into one. If you, as a technical writer, do not understand the subject you are dealing with, how can you possible expect to make your reader understand it?

So, technical writing is not about writing alone. The truth is that a technical writer must do a lot more things apart from writing. You can read my earlier post on this topic here.

Ingredients of Good Documentation #4

Judicious use of Screenshots

Screenshots are images; and images, as we all know, are bulky. How many of us prefer bulky documentation folders that eat away into our disk space and slow down the response time of programs? So, the question you need to ask is this – are screenshots necessary?

Screenshots are a must in printed user manuals. But do you really need them in your online help? First, let’s try and understand how an online help is used, specifically in the case of software applications. The application is running on one window and the help file is open in another window. The user is probably just tabbing between the 2 open windows. Given that the user is already seeing the screen on one active window, does your guide really need to show static images of the same screen?

The obvious answer is no!

Screenshots, however, are not totally redundant. They are especially useful while explaining dynamic screens whose appearance changes based on user input – a configuration screen, for example.

Choose the Multiple Equipment option to enter details of several equipments together. The displayed screen looks as shown below. (Place a screenshot)

This example probably warrants a screenshot. Not only does the screenshot help the user verify that he has reached the correct screen, but it also provides context for the steps that ensue.

Ingredients of Good Documentation #3

Intelligent Content for the Intelligent User

Not all users are the same with regard to their appetite for information; yet it is never a great idea to underestimate the intelligence of your reader. Making this distinction early on can help you write content that is relevant and useful to your specific user.

For example, while writing API documentation, you can do away with explanation of terms like Class, XML, SOAP, etc, unless specifically warranted (like in the case of glossaries or tutorials on those specific topics). This will help you keep your content crisp and to-the-point.

Here’s another example:

This is the help page for the User Information screen of an ecommerce website:

1. Enter your name in the Name Field.
2. Enter your email ID in the Email ID screen. (and so on)

Do you really need this explanation? I would instead prefer a one-liner that asks me to enter my personal particulars in the respective fields provided. I think I am intelligent enough to figure out that my name must go in the Name field. Aren’t most of us?

Ingredients of Good Documentation:#2

Logical Flow of Information

If the user sees screen/options 1, 2, and 3 in that order, your user guide MUST explain those steps in the same manner.

If you thought this is elementary, you’ll be surprised to know how often this basic rule is flouted. For example:

1. Select the page you want to print. 
2. Click Print. 
3. If you do not wish to generate a color print, choose Grayscale from the Options drop-down list before clicking Print.

Here’s an example where steps 1, 2, and 3 are explained in the order 1, 3, and 2. This sequence is confusing.

Here’s a better and straight forward way to explain the same sequence: 

1. Select the page you want to print. 
2. Choose Color from the Options drop-down list for a color print. Select Grayscale to generate a print in gray scale. 
3. Click Print.

Ingredients of Good Documentation:#1

Simple language

A technical writer colleague of mine once wrote the following in tutorial meant to explain business rules:

• YoungRule – Rule to be applied if the applicant is less than 25 years old
• MiddleAgedRule – Rule to be applied if the applicant is between 26 and 50 years old
• Codger – Rule to be applied if the applicant is more than 51 years old

A few weeks later one of our customers wrote a support mail pointing out that there was a mistake in our tutorial. The rule called “Codger” should perhaps read as “OldRule”.

He was right; but my colleague was not wrong either. A quick look at the dictionary will tell you that the word codger means old man.

But that’s the point – do you really want your reader to make a dash for the dictionary while reading your user guide?