How often have you come across a user manual that claims to solve a problem, but actually ends up confusing more than helping? If you're a typical user, it probably happens more often than not. Such badly-designed content leads to dissatisfaction and frustration, a poor impression of product quality and (for the company that sold you the product) increased post-delivery support time and costs.
That's where smart documentation comes in. Smart documentation understands end-user behavior and is aligned to user needs in the most practical manner possible. And in this article, I'm going to offer some practical tips to help you build user content that is suitable, accessible, and readable.
- Understand your audience
Know who you are writing for and what the audience needs to know. This helps you to decide on both the depth and breadth of information that needs to be captured, and the kind of language to be used (for example, language and content would be different for experts and beginners). The key here is to give users only what they want — nothing more, nothing less.
- Have a task-oriented approach
Most products are functional in that they allow users to perform specific tasks. Adopt a task-oriented approach whereby you develop content based on the tasks that can be performed using the product. For example, if the product allows you to configure a network, your table of contents should include heads like "Creating a network", "Configuring network settings" and "Deleting a network".
- Ensure a logical flow of information
Study the product well enough to understand what happens first, next, and last, in a progressive fashion. This vastly improves the accessibility of information in your document.
- Use modules
Break your information into small and manageable chunks, where each portion supports one specific purpose or idea. Such chunks are easier to process by readers, and indicate clear thinking on your part. Modular writing also promotes ease of maintenance, and makes it possible to reuse information through internal linkage.
- Use a table of contents
A table of contents gives a birds-eye view of the scope of the document. Ensure that this is comprehensive, well structured, and has a modular layout. This approach enables users to better identify the information they need.
- Use meaningful and consistent labels
Clear and informative labels help users identify information quickly and correctly. Avoid using generic label titles, and keep labels short and to the point.
- 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 the most common information a user would need.
- Consider the location of critical information
It is human nature to first glance at the center of the page or screen and then at the upper-left corner. Attempt to format your content such that the crux of the material is close to the physical center of the layout, and the main headings are in the upper-left corner.
- Use adequate illustrations
Surprisingly, images are the most under-estimated component of any document. A document that is visually appealing is always more usable. Illustrations (pictorial representations, charts, process flow diagrams) form an integral part of the content, engage the reader's attention and reinforce the content they support.
- Tabulate information wherever possible
Tables improve the readability of information. Use tables when objects need to be described on different bases, or when comparing objects across different dimensions.
- Provide examples
Demonstrate your concepts and explanations with analogies, examples, or case studies. Examples help users grasp the concepts quickly and with better understanding.
- Include troubleshooting tips
When documenting procedures, analyze possible failure scenarios and tell the user how to deal with them when they occur. If you have a separate troubleshooting manual, direct the user to that document for more information.
- Construct a good index
It is generally observed that if a document is badly designed, users look for the information they need in the index. Cover your bases by capturing critical key words in the index to facilitate information retrieval.
- Edit and review
Edit your document to ensure that it conforms to appropriate guidelines for completeness, language, spelling and grammar, consistency and formatting.
- Perform a "reality check"
Ensure that the document is tested in tandem with the product, to expose any deviations between what has been written and reality. Deviations should be corrected and the test procedure should be repeated to ensure that no new errors were introduced in the correction process.
Remember that a user manual is all about enhancing user productivity and reducing customer support time, costs, and effort. A good document serves as training material for a new user and a support document for returning users. Conforming to the aforementioned guidelines ensures better information access and usability, reduced support time and improved customer satisfaction.
source post [tech republic]