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.

Customer support

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.