7 Tips to Creating a Usable Technical Document

Bookmark and Share

binders2For a technical document to be of use to its intended audience, its contents must be accessible. Since most technical documents aren’t intended to be read from beginning to end, the reader must be able to easily and accurately locate the specific information he or she needs. Key document accessibility features may include

  • A table of contents
  • An index
  • A site map
  • Color coding
  • Page numbers
  • Titles and headings
  • Links

Without such features, the reader will struggle to locate information, and the document will consequently become ineffective and potentially useless.

Here are seven tips to creating a usable technical document:

Use Headings

Headings and sub-headings make it easier for your reader to find information. Unlike a novel, a technical document has sections of information that the reader may need at different times. Headings separate the text into pieces, making it easier for readers to find what they’re looking for.

Use Bulleted or Numbered Lists

Use bullets for a non-sequential list of three items or more. Since a sentence with more than three list items is cluttered and difficult to read, a list makes the information easier for the reader to digest. Likewise, use numbers for steps or processes that the reader must complete in sequential order. Procedures and numbered instructions written in narrative form can be confusing.

Delete Unnecessary Words

Extra words can interfere with the relevant material and clutter your document. Therefore, look for and remove unnecessary words and phrases such as

  • That
  • Who is
  • Kind of
  • Sort of
  • Type of
  • Really
  • Basically
  • Too

Use a Consistent Voice

Choose the voice for your document and keep it consistent throughout. Writing in the present tense is least confusing to your readers, especially for step-by-step procedures. In general, avoid using future tense or passive voice.

Explain Uncommon Terms

Don’t assume your reader is an expert on the document’s subject matter. If you think the reader may be unfamiliar with a term or concept, define or explain it. Otherwise, everything after that could be confusing or misunderstood.

Be an Advocate for your Reader

Write your document for any reader with any level of expertise. In other words, the document should be useful to both a novice and an expert. So while your subject matter expert’s job is to ensure the document’s content is accurate, your job is to advocate on your reader’s behalf.

Proofread

Proofread your work before submitting the final version. Even if you only made a few minor changes in your last revision, proofread it again—you may have accidentally left out or deleted a word.

Overall, the purpose of a technical document is to provide a large amount of detailed information in a clear and concise manner. You’re doing a disservice to your readers if you make information difficult to find.

“That writer does the most who gives his reader the most knowledge and takes from him the least time.” ~ Charles Caleb Colton (1780-1832)