Metrics to Improve Your Documentation

by Bradley Nice, Content Manager at ClickHelp — all-in-one help authoring tool

Technical documentation is meant to support end-users of this or that product and give them as much information as possible. The information should be relevant, accessible, clear, and readable. It means that technical documentation should be of high quality. But how can one measure the quality of text? Well, the notion of quality is not an easy one when we talk about documentation. Of course, it presupposes effectiveness. The problem is that it is not an easy task to measure the effectiveness of documentation. We are going to discuss it in this post.

Readability

One of the first things in measuring quality of the document is to check its readability. Is the text clear and precise? It should be written in a simple language avoiding jargon words. The readers should not wrack their brains to understand what the author is talking about. No ambiguity is possible. No grammatical or spelling errors are possible. The text should always be consistent and logical now matter how many authors are engaged into the workflow.

Today, some help authoring tools offer to use readability metrics to improve the quality of the documents. It is the so-called readability scores. Readability itself consists of different parameters: time to read metric, flesh reading ease, SMOG index, and many other parameters. Here you may find more information about them.

Quality of Content

Here we are talking about whether the content is up to date and has the additional information: related materials, overview, definitions, purpose, etc. If the company uses online documentation, one should update it regularly. It is a good idea to identify different versions of the documents as readers must be sure that they are using the most recent one. Additional information should always be at hand — it describes the procedures. For example, who may be responsible for this or that procedure, or whom the document is meant for, the end results of the procedure, specific terms, etc. Another substantial aspect is whether the content corresponds to the reader’s needs. If readers cannot find information they need, it means the content of the document leaves much to be desired.

Navigation

Navigation is one of the aspects that may affect the quality of technical documentation. It is the ability of a reader to find the relevant information in the document. When we are talking about paper documents, readers use the following elements to find what they are looking for: table of contents (TOC), headings, division of the text into parts, etc. As for online navigation, this is something of great importance. Not only the above-mentioned elements are used, search function does a great deal of job. It can be of two types: by index and full-text search. Besides, online documentation contains hyperlinks that enable us to reach out to the relevant information in a matter of seconds.

Availability

It should be evident for a reader where the document is located. Ideally, readers should be able to find the relevant document very quickly. Availability is usually affected in a negative way if the users need special tools or applications to read documentation. It takes time to install or to find them. Not everyone knows how to do that. It should be both convenient to view documents on the screens of devices and print them.

Layout

The main question here is appropriate colors, fonts, and other visual elements. An author should check whether they are going to be suitable both for online and printed versions. An author should check if the document is consistent in general: the division into logical parts and paragraphs, the labeling of headings, compliance with the company’s style and guidelines.

So, metrics may drastically improve quality of your documents. When you choose a HAT be sure that it offers you a wide range of them. You will automatically see what should be changed.

Do you rely on metrics when you write your docs?

Have a nice day!

Bradley Nice, Content Manager at ClickHelp.com — best online documentation tool for SaaS vendors