Technical writing has a seemingly simple goal—to help readers in their efforts to use a particular product and thus make their lives easier.
That can range from providing information about a new digital camera model to a user manual for complex diagnostic software.
In either case, to fulfill its purpose, technical writing must be of high quality.
But how can you measure that?
Regardless of the technical documentation type, there are certain metrics that you can track and improve to raise the quality of the documentation.
Let’s start with the first one.
Accessibility
There are many types of technical documentation, but the purpose of most of them can be reduced to a simple statement—to provide help to end users.
That’s why quality documentation is also easy to access.
Since the users usually read technical documentation to learn something or solve their problems, it’s understandable that they don’t want to spend unnecessary time trying to find it.
If they do, they might become frustrated and go to a competitor who has their documentation easily accessible.
So, what can you do about it? Let’s look at the example from WhatsApp.
The link to their help center with technical documentation is immediately visible when you go to their website.
Therefore, the user doesn’t have to dig through the subpages or external links to find what they’re looking for.
For example, it takes only three clicks of a mouse to get from the WhatsApp homepage to a user guide about updating the app.
Another element of accessibility that WhatsApp documentation does right is not asking its readers to jump through hoops to be able to read it.
What do we mean by that? In addition to being easy to locate, technical documentation should be easy to open and read without installing special programs or apps.
You can access the mentioned WhatsApp documentation through a browser; even the users with the most basic computer knowledge already have at least one at their disposal.
Alternatively, you could make your documentation accessible as PDF or MS Word files, which are both widely used and users are familiar with them.
For instance, Dell users can access manuals as PDFs or read them in their browser.
To sum up, there’s little point in having even the most user-friendly and meticulously crafted technical documentation if the users have trouble finding or accessing it.
All the effort you poured into its quality could go unnoticed.
Quality
Do you want to have technical documentation of the highest quality? Fill it with great content.
The quality of what you have in your technical documents isn’t something you can necessarily measure objectively.
Quality depends on many factors. How complex is the subject matter? How accurate is your information? Do you use a clear writing style? Is your formatting on point?
We barely scraped the surface of this issue with those few questions. However, there are ways to ensure that you consistently produce high-quality documentation: setting up benchmarks.
Tom Johnson, a technical writer and blogger, recommends using checklists like the one below.
As he argues, assessing documents against a list of characteristics is superior to trying to evaluate them against some abstract criteria.
The more comprehensive the checklist is, the more consistent the quality of your documentation will be. For instance, Johnson has 75 characteristics on his list.
In addition to assessing your documents with a list of criteria, a great way to produce quality content is by following a style guide.
There are many guides available online, e.g., the SUSE Documentation Style Guide.
It provides the reader with best practices in writing technical documentation, be it formatting, using the correct terminology, or some other of the dozens of topics it covers.
Whether you use that style guide or some other, the point is to stick with their practices to make the quality of your documents consistently high.
The quality of your documentation can be an elusive metric to keep track of.
Still, by implementing simple strategies like using checklists and style guides, you can elevate it almost instantly.
Usability
As you probably know, users don’t read technical documents for fun and literary pleasure.
When they reach for such a document, they have one purpose in mind: to solve a problem or learn something.
Users want to achieve that goal, and if you pay attention to usability while creating documentation, they shouldn’t have a problem doing that.
But what makes a document usable?
Cassandra Race, a technical communication expert from Kennesaw State University, summed it up like this:
In other words, when a user can quickly and easily follow a document and achieve their goals, that document has high usability.
For that to happen, a technical writer should remember that the user is most likely interacting with the product for the first time, as Kesi Parker reminds us.
That means that a writer should create clear, step-by-step documentation, whether it’s a manual for a digital camera or a guide through a software interface.
For example, Google created a technical overview of Native Client, a sandbox for running compiled C and C++ code in the browser.
What makes it very useful for readers is the patience with which the writer approaches the matter.
They didn’t assume that readers knew about the product and didn’t skip any steps. For instance, here are the subheadings in the technical overview:
- Why use Native Client?
- Benefits of Native Client
- Common use cases
- How Native Client works
- Structure of a web application
- Where to start
As you can see, if a user wants to learn about Native Client, its technical overview covers all the bases.
In conclusion, usability is all about providing your readers with documentation that can fulfill its purpose. Here’s how the previously mentioned Tom Johnson explains it:
Writing documentation that is helpful and easy to use isn’t a simple task.
However, focusing on its purpose of solving problems and providing the information is crucial in increasing its usability and, therefore, overall quality.
Readability
As obvious as this may sound, writers should keep in mind that a user will read their text, and when they do, they should be able to understand it.
As Suzan Last, a technical writing professor at the University of Victoria, puts it, the underlying purpose of every document is to be read.
That’s why readability is essential, regardless of the type of technical documentation.
To improve the readability of your text, you can use readability metrics and scores like the Flesch Reading Ease score, which considers word and sentence length.
As you can see above, the score can be between 1 and 100. The higher the score is, the easier it is to read and understand the text.
Also, the score is accompanied by the estimated reading grade. For example, if your text scores between 80 and 90, that means that the 6th grader could comprehend it.
You can check the Flesch Reading Ease score with various tools like Readable, but also in MS Word.
Besides word and sentence length, the use of jargon can have a significant impact on readability.
If you liberally use technical terms in your writing, you could discourage a big part of your readers who don’t have your level of knowledge.
On the other hand, even the experts in your audience can appreciate clear and concise writing in simple language.
Tools like Hemingway can warn you if there is too much jargon in your document, as the readability score the app provides takes that into account also.
Here is a passage from the ArangoDB documentation that got a poor score.
As you can see, the sentences are overly long, and the use of jargon makes the text difficult to understand, especially for new users.
Adopting a more straightforward style will improve the quality of your documentation. That way, both the experts and laymen will be able to get the information they need easily.
Navigation
Users who come to a technical document most likely don’t have a lot of time to spare—they need information, and they need it quickly.
Therefore, creating a technical document in which readers can find what they need without wasting time is a crucial element of documentation quality.
Writers can do that by implementing elements that make navigation in the document easier.
Whether it’s online API documentation or a refrigerator manual on paper, most readers will first turn to the table of contents—a list of all the topics covered in a particular document.
Above, you can see a table of contents from a scientific paper.
When a reader wants to find information about, for example, clinical safety as a basis for a decision, instead of perusing a whole paper, they know that they can turn to page 11.
A table of contents is very helpful for navigation in the online technical documentation, also.
For instance, take a look at the table of contents from a wiki page about User Experience Design below.
As you can see, every category has subcategories divided further into questions. That way, navigation in the document is simple and effective.
However, what makes it even easier is the use of links. Linking within a document is an excellent way to connect similar topics and logically guide the reader.
Below, you can see how Breadwinner did that in their documentation created in Archbee.
Most online documentation tools have the option to insert links.
However, in addition to that, Archbee has a powerful search function that makes navigation in the documentation a breeze.
Simply typing the term in the search box allows a user to find every instance where it shows up.
Combined with a table of contents and links inside the document, that is everything a quality technical documentation needs when it comes to navigation.
Layout
A logical layout is another element that a technical document of high quality should have.
In the previous section, we mentioned the importance of easy navigation in the documentation.
The document’s layout goes hand in hand with it—when a piece of writing has a good layout, finding your way around it is easier.
Also, the better the layout of the document is, the easier it is for users to follow it, read it and learn from it.
As you know, technical documentation that provides such experiences is high-quality documentation.
So, what can we consider a great layout for a technical document?
Let’s take a look at the example below.
Let’s break it down to see elements of its layout.
As you can see, there is a heading at the top of the page, followed by a subheading. That makes it easy for a reader to identify the topics that this part of a manual deals with.
The text also has two bulleted lists. They are useful for emphasizing the main points of a broader topic.
Since the user should be able to find the most important information easily, lists are great for that purpose.
For presenting information in sequential order, you can also use numbered lists:
Furthermore, having shorter paragraphs makes the text easier to read and follow, as Ash Norton suggests in her article.
As you can see in the first example above, there are no walls of text.
Another element worth mentioning is fonts.
It is generally recommended that you don’t use more than two types of fonts—one for headings and subheadings and one for the rest of the document:
When you combine the elements we mentioned in this section, you will get a document with a layout that is easy to follow and lends itself to presenting information in the best possible way.
And that will undoubtedly improve the quality of your documentation.
Customer Satisfaction
Another way to measure the quality of your documentation is by assessing its users’ satisfaction.
Customer satisfaction can tell you if you are putting emphasis on the important elements of your documentation while writing it.
Therefore, you can use the customers’ feedback to make your documentation more accessible, usable, readable, better structured, and easier to navigate—in other words, improve every metric we mentioned so far.
So, how to know if your users are satisfied with your documentation? The simplest way is probably the most effective—ask them.
One of the easiest ways to do that is to insert a question inside your document: “Was this information helpful?”
Above, you can see how Google implemented that in their Google Cloud Help documentation.
It’s a simple binary choice, but the amount of “yes” and “no” answers can give you valuable information about the quality of your documentation.
Below is another example from technical documentation that Pathfix created in Archbee.
It’s a convenient way to gather feedback—it doesn’t require any particular technical knowledge from users and takes virtually no time.
However, although this method is useful, it can’t tell you anything about the reasons why the readers might be satisfied or dissatisfied with your documentation.
To learn more about that, you can use surveys.
As Josh Fechter advises, you can incorporate surveys on your webpage, send them via email, or use social media.
Below, you can see a part of one such survey.
As you can see, you can ask users to type their answers, offer them multiple answers to choose from, or use a combination of methods, as you can see below.
The key element is to assess how many questions you will include and how much time you will ask users to spend on a survey—if you ask too much from them, they might not bother with filling out a survey at all.
All in all, customer satisfaction is an important metric that can help you improve the quality of your documentation.
After all, you write it for your users, and they can tell you best if you’re doing a good job.
Conclusion
In this article, we’ve presented you with crucial elements of quality technical documentation.
Why should you pay attention to them?
It’s simple—the state of your documentation reflects your product or service. If your customers see quality documentation, they will know you’re serious about your work.
That’s why having accessible documentation, polishing it to perfection, including relevant and helpful information in it, writing it with your audience in mind, structuring it logically, and making it easy to navigate should be priorities for every technical writer.
