6 Ways to Improve Your Product Documentation

Software products without documentation are essentially unimaginable.

The reason is simple.

No company would invest resources, time, and effort into creating a software product and launching it to compete in the market just to leave its customers without any information resource about that product.

That being said, not all product documentation is created equal. There are good and bad examples, and everything in between.

However, all product documentation can be improved. How? That’s what this article is here to teach you.

So, what are we waiting for?

Appoint a Documentation Owner#

Your software product undoubtedly has a product owner.

The product owner is one of the key figures in ensuring the product’s success, maximizing its value, and steering the development team in the right direction.

You might not call that person a product owner if your team doesn’t work with Agile methodologies.

For instance, some alternative titles for the same role include value manager, on-site customer or product champion.

Regardless of the terminology, your software product surely has a person responsible for it.

But what about your documentation? Who is responsible for providing great product documentation and making sure it meets the highest standards?

If you don’t have a clear answer, it’s time to appoint a documentation owner.

Assigning one person to take care of the documentation can prevent the diffusion of responsibility, a phenomenon where no one in the group takes responsibility for a task because everyone thinks someone else will do it.

McCombs School of Business on YouTube

In other words, if you don’t appoint a documentation owner, there’s a risk that the departments and the employees will pass the hot potato of product documentation among themselves.

Instead, put one person in charge and give them clear responsibilities, and the documentation will improve.

For example, take a look at the poll from Reddit below. It can give you an idea of how confusing documentation ownership can be.

Source: Reddit

To avoid that kind of buck passing, you should determine who the documentation owner is.

Some experts like Erin Grace, a software industry veteran, and Alice Spies, a customer success specialist, argue that the product owner (PO) should also be the documentation owner.

Here’s how Grace puts it:

Illustration: Archbee / Data: LinkedIn

As she explains it, product owners know every detail about the product, its purpose, the customers’ needs, and the direction the product should evolve in.

And that kind of in-depth knowledge of the product can only benefit the product documentation.

The docs should be regarded as an indispensable part of the product, a resource that provides all the necessary information.

Therefore, it’s logical that the product owner takes responsibility for the documentation as well.

Regardless of who takes the reins, it’s essential that they embrace the responsibility for the documentation and its quality.

Test the Usability of Your Documentation#

Is using your product documentation easy? That’s the crucial question you need to answer to improve your documentation.

As you probably already know, product documentation should be an accurate, relevant, and helpful information resource for your customers.

When customers use your documentation, they have a reason for it, whether it’s learning about a particular feature, solving a problem with the product, or something entirely different.

How does usability fit into that? Josh Fechter, a technical writer, entrepreneur, and investor, explains it like this:

Illustration: Archbee / Data: Technical Writer HQ

So, in other words, usable documentation helps users with anything related to your product.

But how can you know if your documentation is usable?

The problem is that the creators of product documentation aren’t in the same position as the regular user.

Whoever creates the documentation is much more familiar with the product than the user.

That’s why you should test the usability of your documentation, and you can do that using three methods:

Illustration: Archbee / Data: Technical Writer HQ

Let’s explain each of them, starting with paraphrase testing.

That type of usability testing is based on a simple premise—if a user knows how to repeat the content in their own words, that shows that they understand it.

And if they understand the content, it’s safe to say that they can use it to achieve their goals.

On the other hand, task-based testing aims to determine how easy it is for users to find the documentation they need and achieve their goal with the help of instructions from the docs.

This type of testing is particularly suitable for testing the usability of manuals, how-to guides, and other instructions.

For example, if we go to Canva’s Help Center, we can test how easy it is to find documentation about using templates.

Source: Canva

As you can see above, there is a large search bar in the middle of the page.

If we type in “How to use a template”, the search function will instantly offer many documents, so finding the right one doesn’t take long.

But finding the right document is just a start; with task-based testing, you need to assess how easy it is to understand the documentation.

For instance, can users follow these instructions once they find them?

Source: Canva

If your users need help finding or understanding the docs, you and your team should make improvements.

Finally, the plus-minus testing method is easiest to understand if we let its inventors, Menno de Jong and Peter Jan Schellens, explain it:

The method involves asking participants to read a text from start to finish and to mark their positive and negative reading experiences with pluses and minuses, respectively, in the margin.

This testing type provides you with direct feedback from users, which you can then use to improve the parts of your documentation that need more attention.

Add Plenty of Visual Content#

One of the most effective ways to improve your product documentation is by enriching it with visual content.

Visuals like screenshots, images, graphs, GIFs, charts, and videos aren’t there only to make your documentation look pretty—although they’ll undoubtedly do that too.

Visuals are very effective in achieving the documentation’s goal of providing easy-to-understand information and helping readers retain the knowledge they get from the documentation.

That’s not just speculation. According to research, most of the world’s population learns more easily through visual materials.

Illustration by Archbee / Data from SSRN

And even if you don’t care about catering to the most dominant learning style, you surely want to create documentation that will efficiently relay information to your users and that they’ll enjoy using.

Because if they open your product documentation and see something like this below, they might lose the will to learn anything about your product.

Source: Screensteps

That wall of text above could easily be improved by adding visuals instead of lengthy paragraphs of detailed explanations.

For example, you can use screenshots to instruct your readers how to navigate the registration page of your product, like Hopin does.

Source: Hopin

It goes without saying that just because you use visuals in your product documentation, that doesn’t necessarily mean you need to abandon every form of text.

In Hopin’s example above, you can see brief explanations of what the screenshots represent.

Moreover, below those visuals, Hopin also provides a more detailed breakdown of what the user is looking at.

Source: Hopin

Visuals enrich documentation and make information easier to digest and retain, but that doesn’t mean the text itself isn’t important.

Often, the most effective approach is to find the right balance between the visuals and the text, and have them complement each other, like in the example above.

Of course, you can make your content purely visual. For example, if you opt for video instructions, there’s no need for written ones.

Source: Hopin

However, in other cases, simply adding visuals to your written product documentation will undoubtedly improve it.

It will provide an enjoyable experience for users and efficiently transfer information to them.

Include Links to Relevant Topics#

When creating product documentation, assessing which pieces of information should be grouped together in one document is challenging.

On the one hand, you want to provide your users with every piece of knowledge they need in one place, sparing them from having to navigate through your docs in the quest for the resources they need.

On the other hand, your common sense tells you not to stuff everything onto one page. That wouldn’t make navigating and finding information any easier.

Luckily, there’s a handy solution—linking to the relevant documents.

It combines the best elements of both solutions we’ve mentioned and eliminates the disadvantages.

Vibhu Dhariwal, a digital marketer immersed in the SaaS world, explains it like this:

It is important to give the right understanding of a subject to the reader. For this, you have to make sure that the navigation is up to the mark.

By linking to relevant topics, you provide your reader with an opportunity to learn more about the subject.

Simultaneously, you make navigation through the documentation easier, so users won’t get lost in it.

Let’s look at how SurveyMonkey links to relevant topics.

Source: SurveyMonkey

Above is a part of their documentation page about the ways to send surveys.

As you can see, they included three links in one paragraph, and every one of them leads to a different documentation page.

For example, if you click on the link about accepting payments, you get transported to the page that covers that topic.

Source: SurveyMonkey

So, thanks to linking, SurveyMonkey’s team can create concise documentation pages that a user can read in a relatively short time and still point them in the direction of additional information that can be helpful.

In addition to including links in the body of the text, like in the example we’ve just examined, you can link to relevant topics at the end of the help article.

AdRoll mainly uses that strategy.

Source: AdRoll

Regardless of where you put your links, they will benefit your users.

Linking to other topics is like drawing a map for your readers, so they don’t get lost in the vast amount of information your product documentation provides.

Maintain Your Product Documentation#

Imagine if your developers constantly added new features, improved the software product, and changed its functionalities.

You don’t even need to imagine—that’s the reality of today’s software development.

As Portia Burton, a developer and specialist in technical documentation, points out, software development moves a lot faster than it used to.

Illustration: Archbee / Data: Heavybit

Therefore, keeping your product documentation up to date is a must if you want it to remain relevant and useful to your customers.

Otherwise, the documentation will quickly lose its value.

The product will change over time, and the information in your documentation will become obsolete, or worse, lack the details that the users need altogether.

That’s why it’s important to update your documentation regularly and in a timely manner as the product gets new versions.

For example, Twitter regularly releases new versions of its API, which can be considered an important software product for developers.

They keep a schedule, and every user can see when the API will be released, deprecated, and no longer functioning.

Source: Twitter

But they also take care of updating documentation so that it reflects the changes in the new versions of their product.

For instance, in version 4 of Twitter Ads API, they added a new Audiences API.

Twitter’s team informed the users about it briefly and included a link to a new documentation page with more details.

Source: Twitter

The documentation accompanying this new feature allowed users to learn about it and use it as soon as possible.

Source: Twitter

So, let’s sum up what Twitter did.

They updated their product with new features and released a new version.

Along with that, they briefly explained some of the most notable changes in the new versions to keep the users in the loop.

But most users want and need instructions that guide them through changes in the product.

Twitter’s team updated documentation to accommodate that need and ensured that the new docs were easy to find.

And that’s how you maintain your product documentation.

Keep up with the product changes, document them, and present your user with new resources.

Track Documentation Metrics#

If you want to improve your product documentation, you need to know which areas to focus on.

Hoping to improve the docs without an insight into what parts actually need improvement isn’t particularly efficient.

Luckily, there is a solution to that problem—you can track documentation metrics.

By tracking how your documentation performs, you can get a clear picture of what you need to improve, what your customers use the most, and what parts of the documentation just take up space.

But first, you should decide what metrics you want to track. They are divided into two main categories—quantitative and qualitative metrics.

Some of the quantitative documentation metrics you can track are:

• Pageviews
• Users
• Pages per session
• Average time on page

Those metrics will give you specific numbers you can further analyze and assess where improvements are needed.

For example, Google Analytics can show you the pageviews.

Source: Semrush

The number of views your pages get indicates what content is the most interesting and relevant to your customers.

Likewise, a low number of views can indicate that the page is unhelpful, that the customers aren’t interested in its content, or simply that it’s difficult to find, to name just a few possible reasons.

Google Analytics can show you many more valuable metrics, so it’s great if it can integrate with your documentation tool.

If you use Archbee for your documentation needs, the integration is easy.

You can add a Google Analytics tracking code to your documentation portal and see how your documentation performs.

Source: Archbee

Let’s turn our attention to qualitative metrics now. Some of them are:

• Readability
• Feedback
• Heatmaps
• Scroll depth

They can be very valuable for understanding how your readers interact with your documentation and which parts are the most useful to them.

There are various software tools you can use to track those metrics.

For instance, using Smartlook, you can get three different types of heatmaps.

Source: Smartlook

On the left-hand side of the visual above is a click map, which shows you where users click on your page the most.

In the middle is a move map that shows the users’ mouse movement.

Finally, on the right-hand side is a scroll map showing what percentage of users reach a particular part of the page.

Those heatmaps let you observe how users interact with your documentation.

For instance, if most of them don’t reach the bottom of the page, that can indicate that there is too much content, and you should split it into multiple shorter pages.

To sum up, by tracking documentation metrics, you can step into your users’ shoes and see where improvements are needed.

The only thing left then is to make those improvements and raise the bar of documentation quality.

Conclusion#

Your customers often rely on product documentation when using your software product.

And who could blame them? Software products can be complex and with a steep learning curve. Having reliable and comprehensive documentation can certainly help.

Although you most likely have product documentation, it can always be better and more helpful to your customers.

We hope this article will inspire you to try some of the ways you can improve your product documentation. The users are sure to appreciate it.