Geeks With Blogs
Technical Writing by Mark Metcalfe, Publications Professional
Suppose that you asked me to help you write a blog. How would you feel if I handed you the unabridged Oxford English Dictionary and told you that "it has every word you will ever need for your blog. It is the most accurate and complete tome you can find!" While technically true (being accurate and complete), the dictionary is not useful for telling you how to arrange the words to make you a competent blogger.

We rightfully stress accuracy and completeness when we describe doodads, widgets, and thingamabobs in technical documentation. However, it is more important to emphasize making documentation useful. 

Useful documentation starts with understanding the intended purpose of the software (or other object), answering the "why" and "how" questions, such as:
  • "Why would I want to (or need to) fill out the fields in this dialog box?"
  • "Why is it important to follow the procedure?" 
  • "How have other people used the product to good effect?" (What are the best practices?)
Answering such questions goes a long way toward developing competency in a user, making information useful, but even that is not enough. If information is difficult to find, your great documentation may be like the proverbial tree falling in the woods with no one to hear it make a sound. You also have to make the information easy to find.

Creating a user experience that is useful depends a lot on your audience. Some customers may need a printed document* with a well-formed table of contents and index; others need to open progressive levels of information using finger-friendly-formatted documentation for mobile devices. In many cases, useful documentation makes information easy to find by providing multiple means of access (such as TOC, index, topic list, and search) that is (intuitively) easy to navigate.

When you put it all together, useful documentation transfers competency knowledge through accurate and complete information that is easy to access and navigate.

Mark Metcalfe

* I worked for a hardware company that needed paper documents in the field. A slick Web help system or video tutorial were not useful forms of information transfer for that user base. Know your audience.
Posted on Friday, February 15, 2013 4:20 PM | Back to top

Comments on this post: Accurate and Complete are not Enough

No comments posted yet.
Your comment:
 (will show your gravatar)

Copyright © TechnicalWriting | Powered by: