More often than not we come across documents that state the obvious about the products they talk about. They fail to attain that extra mile to explain basic troubleshooting techniques or problem scenarios that help users to overcome complex situations smoothly.
Content that is not designed well to suit the users’ requirements leads to:
Dissatisfied and frustrated users
Poor impression of product quality and in-turn, the Organization
Clogged customer support lines, with users trying to obtain immediate, real-time support for their problems
Increased post-delivery support time and costs.
Documentation that understands end-user behavior and is aligned to meet the users’ requirement, in the most practical and intelligible manner, can be categorized as a “Smart Document”.
Documentation must have complete support from Managers and Engineers, and the significance and scope of every document must be clearly known.
Let us see some reasons why our documents fail to comply with user needs.
Disorderly and sketchy analysis of audience and content
Poor organization of content, resulting in critical information getting buried in irrelevant baloney
Misdirected or inadequate analysis for presenting content.
At any time, information must be Available,Suitable, Accessible, and Readable.
Here are some ways to analyze, organize, and present your information in a user-friendly manner.
1. Understand your audience
Know who you are writing for and what the audience needs to know. This helps you to decide on:
The depth and breadth of information that needs to be captured
The kind of language to be used.
For example, language and content would be different for Managers vs. Beginners. “Nothing more, nothing less” should be the mantra. Give the users only what they want
2. Know the purpose and output
Know why you are writing the document.
It could be an “Operators Manual”, which requires in-depth information or it could be a “Getting started” document, which gives you an overview of the product and its features.
3. Have a task-oriented approach
Most products are functionality-oriented, that is, they allow the user to perform a specific task. Adopt a task-oriented approach and develop content based on the tasks that can be achieved using the product. For example, if the product allows you to configure a network, your Table of Contents (TOC) might look like this:
About the network
Creating a network
Configuring network settings
Modifying network settings
Deleting existing networks.
4. Ensure a logicalflow of information
Study the product well enough to understand what happens first, next, and last, in a progressive fashion. For example, do not talk about “modifying network settings” before “creating a network”. This vastly improves the accessibility and retrieval of information from your document.
5. Write modularly
Break your information into small and manageable portions, where each portion supports one specific purpose or idea. Such chunks are easier to process and indicate clear thinking. This promotes:
Ease of maintenance: If only one topic of a chapter needs to be updated, you need to update only one paragraph, and not a bigger chunk of information
Reuse of information/Single sourcing: At times, we do have overlapping information across documents. If content is modular, it needs to be updated only once and can be reused across the documents.
Ease of information retrieval.
6. Seven plus or minus Two limit
George Miller, a Cognitive Psychologist has proved that 7+/-2 is the maximum capacity of memory retention, and the amount of information we can receive, transmit, and remember, at a given time. It is perceived that breaking information into not more than 7+/-2 chunks helps to alleviate the bottle-neck and retain more information.
If your topic exceeds 9 paragraphs, try to further categorize information to ensure that the chunking limit of 7+/-2 is observed.
You can visit http://www.well.com/user/smalin/miller.html for more information.
7. Create a comprehensive TOC
A TOC gives a birds-eye view of the scope of the document. Ensure that the TOC is comprehensive, well structured, and has a modular layout.
8. Use meaningful and consistent labels
Clear and informative labels help the reader to identify their information correctly. The label should be indicative of the content within. Here are some guidelines for creating labels.
Avoid generic labels such as “Overview” or “Introduction”.
Create specific labels - “About the Network Interface” or “Generating business reports”
Keep labels short. Avoid using long phrases or sentences.
9. Use simple and clear language
Do not use jargons. Use familiar and common words
Keep your sentences short and precise. Long and confusing sentences take longer to understand
Use the present tense to avoid a chaos of complex verbs
Convey the message in the first few words of your sentence, and use active voice
Address a single user: You.
10. Be consistent and specific
Use similar words, formats, labels, when presenting similar topics. This helps to:
Avoid ambiguity
Improve reusability and simplify translation or localization
Merge content from multiple documents.
11. Write in a conversational tone
Adopt a “Frequently Asked Questions (FAQ)” approach. This methodology allows you to bridge the gap between the product and the user with greater ease, and also include most information that any user would need to know.
12. Place critical information suitably
It is human behavior to first glance at the center of the window, and then to the upper-left corner, while reading. So try to format your content such that the crux of the topic is somewhere close to the center of the window and the main headings are in the upper-left corner. This makes scanning the document easier.
13. Provide advance navigators
Advance navigators give an idea of the purpose of the document and how to use it. It is a good practice to include the following sections as parts of the first chapter.
Purpose
Target audience
Document history
How to use this document?
Conventions used
Related documents and training
Technical support.
This gives the user a sense of orientation and navigation.
14. Use adequate illustrations
Surprisingly, graphics are the most under-estimated components of any document. A visually appealing document always looks more usable.
Illustrations such as pictorial representations, charts, process flow diagrams, and so on, form an integral part of the content and:
Engage the reader’s attention
Are easy to understand
Reinforce the meaning of the content it supports
Consume less space compared to printed information.
15. Tabulate information wherever possible
Tables improve the readability of information. Situations when the same information needs to be known for multiple objects form the main contenders for tables. For instance:
Product interfaces and their functions
Toolbar icons and their corresponding meaning, and so on.
16. Provide suitable examples
Demonstrate your concepts and explanations with analogies, examples, or case studies. Examples help users to grasp the concepts quickly and with better understanding.
17. Include troubleshooting tips
While documenting procedures, analyze possible failure scenarios and tell the user how to deal with such scenarios, if encountered. If the product has a separate Troubleshooting Manual, direct the user to that document for more information.
18. Avoid screen-shots
Screen-shots are difficult to maintain and render the document bulky, considering the ever-changing user interfaces. They also affect deadlines adversely. Ask: Does this screen-shot add any value to or provide additional information to that already provided?
Be cautious. Use screen-shots and explain them only if:
The GUI is poorly designed and labels are misleading and ambiguous
There is a client requirement.
Show how the main interface looks like, or have a separate “Graphical User Interface (GUI)” document that would contain all the critical interfaces and their descriptions. This makes it easy to update the screen-shots.
19. Build a good index
It is generally observed that if a document is badly designed, users look for the information they need in the index of the document. So to make up for the rest of the document, capture the critical key words in the index, to facilitate information retrieval.
20. Edit and review
Edit your document to ensure that it conforms to appropriate guidelines for:
Completeness
Language
Spellings and grammar
Consistency
Formatting.
21. Test the document along with the product
Managers must plan the first hand-off of the document at the testing stage of the Software Development Life Cycle (SDLC). This practice discloses any loop-holes and gaps that might exist in the documentation and the product. The errors reported can be eliminated before the document is out in the market.
It is all about enhancing productivity and reducing customer support time, costs, and effort.
A good document serves as training material for a new user and a reference guide for returning users. Conforming to the aforementioned guidelines ensures:
Better information access and usability
Reduced support time
Improved customer satisfaction.
Keep your ears open to the users’ concerns. Step into their shoes when you write and we can be sure that the end result will be much better than you expected. So get smart!
Chillibreeze's disclaimer: The views and opinions expressed in this article are those of the author(s) and do not reflect the views of Chillibreeze as a company. Chillibreeze has a strict anti-plagiarism policy. Please contact us to report any copyright issues related to this article.
Out of 5 “chilies”, our editorial team gave this article...
—About our writer:
Vaishali writes to keep her heart beating while juggling a job as a Business Development Strategist and managing family. At times, she sketches stories on canvas. Born and brought up in Mumbai (formerly Bombay), she lived in Bangalore for a couple of years and currently lives in Pune with her husband. She is shameless when it comes to advising people on the "de-consuming" strategy for a habitable planet. With "passion" as her middle name, she captures time through her canvas, guitar, cooking, dabbles in poetry, haiku, and short stories, trying to make sense of the world.
>> Read more articles written by Chillibreeze writers:
