Tips for Keeping Your Product Documentation in Great Shape

Dragos
Dragos
Founder, robot with feelings. From planet Aiur.

Nowadays, product documentation maintenance is more important than ever. In this article, we’ll share with you some tips on how to keep your product documentation in great shape.

📚 Table of contents

Looking for a documentation platform that's easy to use?

Try Archbee for free. Capture complete product knowledge from across your company and publish it with fully customizable portals.

In today’s world of software products, product documentation is more important than ever.

Software products are often innovative, and full of features and possibilities, while customers are rarely experts who intuitively know how to use them.

That’s why you should keep your product documentation in great shape.

It’s a resource for anyone using your product, it helps your team, and sometimes it’s the first point of contact between your product and your potential customers.

In this article, we’ll share with you some tips on how to keep your product documentation shipshape—and more.

Update Documentation Along With the Product

SaaS products are constantly changing and evolving, bringing new features and possibilities to customers.

That’s the nature of software products, and any business that aspires to establish itself on the market works hard to keep up with the changes.

However, the products aren’t the only thing that should be regularly changing—the product documentation needs updating as well.

If that doesn’t happen, the documentation will become outdated and virtually useless in a short period of time.

For example, data from Storemaven indicates that approximately half of the most successful apps release updates very often—almost every week.

Source: Archbee

What does that tell us? Well, in short, if we don’t update product documentation along with the product, it will cease to be relevant.

And documentation that isn’t relevant can’t fulfill its purpose of being a helpful resource of information and knowledge about the product.

To make updating documentation easier, you can schedule reminders to do it regularly.

For instance, Svetlana Novikova, technical writer at JetBrains, advises setting up an automated reminder in Slack.

Source: blog.jetbrains

As you can see, their team set up a Slackbot to remind them to update product documentation every Monday.

How often you and your team revise documentation is up to you, as long as you ensure that it doesn’t become outdated.

For example, releasing major features should be accompanied by corresponding documentation as soon as possible, while some minor bug fixes can be documented at scheduled intervals.

Of course, you should also notify your customers of the changes in products and product documentation.

Having a changelog is an excellent way to provide them with all the news they should be aware of.

Below, you can see a part of the Intercom’s changelog.

Source: Intercom

As you can see on the screenshot above, it has a search bar, and you can also filter changelog entries by the product area they belong to, making it even more helpful to users.

To sum up, updating your product documentation shouldn’t be an afterthought—if you want it to be top quality, it should be one of the priorities.

Make Someone Responsible for It

If you want to keep the high quality of your product documentation, someone needs to commit to maintaining it.

That’s because if you’re not in a big company that has dedicated personnel for every aspect of the business, it’s possible that managing the documentation is passed around.

Sometimes the developers write a part of it, a customer support agent doesn’t update a document until the following week, and a technical writer is busy with another project—there are endless scenarios in which product documentation can fall behind.

That can happen because of diffusion of responsibility:

Source: Archbee

If we put that in the context of product documentation, the situation is fairly straightforward—the more people are involved in handling the documentation, the less likely it is that one of them will claim responsibility for it.

And that is a problem because it can significantly impact its quality.

Luckily, the solution is simple—directly assigning the task of maintaining documentation to one person.

Ideally, it should be someone who is good at it and enjoys doing it, like this Reddit user below:

Source: Reddit

Although he’s not primarily a technical writer, he enjoys that part of his responsibilities.

If you have a person in the company like that, it’s a win-win situation—the documentation is in safe hands, and the employee gets to work on what they love.

Assigning a team member to a piece of documentation is easy if you use Archbee for your product documentation needs.

You can set up document verifications and assign a person from your team to periodically check and verify the documentation.

You can see how that works in the video below.

Source: Archbee on YouTube

That way, they get a regular reminder, and you ensure that the document is checked, updated, and verified.

In other words, the team knows that someone is responsible for the documentation.

Encourage Team Contributions

In the previous section, we examined the importance of assigning the responsibility of polishing product documentation to one person.

However, that doesn’t mean that the documentation is off-limits for the rest of the team.

Having a person in charge of documentation is important, but building an excellent resource for your customers can also be a collaborative effort.

Although that might sound contradictory, it’s simple—just because one person has the responsibility to maintain documentation, that doesn’t mean that no one else should offer ideas and contribute.

That could be very beneficial for the quality of the documentation itself.

Employees from different departments have different perspectives on the product and might have valuable insights.

For instance, take a look at the part of Twitter’s API documentation below.

Source: developer.twitter

That type of documentation can significantly benefit from software developers’ and engineers’ contributions.

They have the technical expertise to write it, or at least contribute to it, and they also know the audience this type of documentation is intended for—they know what is important for readers and what to pay attention to.

You can encourage others to contribute by using tools like Archbee, which has many features for easier collaboration.

For example, you can leave comments in documents and assign them to people on your team.

Source: Archbee

When you do that, they get a notification so the collaboration can continue without the need to have everyone online all at once.

Source: Archbee

Whether it’s a member of the sales team, customer support team, or software developer, there’s no reason not to include them in the collaborative effort of maintaining top-notch product documentation.

If you do, you can end up with a much better and more well-rounded product.

Review Support Tickets Regularly

Businesses that want to be successful should always keep in touch with what their customers want.

Whether those customers have needs, wishes, problems, or all of the above, taking care of them is crucial.

Luckily, you seldom have to guess what your customers want.

If they can’t figure out something related to your product, they’ll probably reach out to your customer support, be it via email, live chat, phone, or whatever method your company provides for them.

And most of them will reach out to you when in need.

According to data from Fullstory, customer experience is equally important as the product—and customer support is a part of that experience.

Source: Archbee

Their concerns and questions can be a valuable resource—you can learn the most common friction points your customers have while using your product and use that to improve your product documentation.

Support tickets, or interactions between customers and the support team, are vital in that regard.

As Ben Goodey, a digital marketing expert, points out, support tickets are different from other forms of feedback—customers provide them to you without you even asking them to.

Source: Archbee

So, how can you use them to improve your product documentation?

You can analyze them. Support tickets come in every day, so you most likely have plenty of material—it’s only a matter of how you want to do it.

For instance, Goodey advises reviewing them manually or with the help of software tools, depending on the number of support tickets and your needs.

A manual approach can involve a spreadsheet, like the one below.

Source: sentisum

As you can see, that spreadsheet contains the feedback from the customer and some additional data about it.

To use that for managing your product documentation, the most important thing is to review your customers’ questions and problems and identify the most common ones—those can provide you with topics for the new help articles in your product documentation.

On the other hand, if you use software tools to analyze support tickets, most of them automate many of those tasks.

For instance, Sentisum can automatically tag and categorize support tickets by multiple factors like topics and intent, make them searchable and create helpful reports, like the one below.

Source: sentisum

When you get a report like that, you can easily see the most common problems your customer support deals with and improve your product documentation so the customers can resolve at least some of them by themselves.

Support tickets are golden nuggets of information—you just need to pay attention to them.

Use Metrics to Track Documentation Performance

Let’s say you and your team created comprehensive, clear, and helpful product documentation, which you poured a lot of hours and effort into.

And while you might be proud of it, you still should keep in mind its primary purpose—do customers find it useful?

Because if they don’t, what you think of it is irrelevant—product documentation serves the customers, and if it’s not doing that, you might have a problem at your hands.

To prevent that, you can use metrics that tell you how your product documentation performs.

For example, one of the valuable metrics is your most and least read topics.

As Lonnye Yancey Smith, executive manager of user assistance at Hexagon, points out, if users visit some pages very frequently, that could indicate possible problems.

Source: Archbee

Therefore, you can pay extra attention to that part of the product documentation and keep it as helpful as possible while your developers look into the element of the product it refers to.

Similarly, parts of the documentation that customers read the least can also point to issues—those pages might be hard to find, or the product features they describe might not be interesting to users.

Regardless, you can get valuable insights into customer behavior, showing you how to improve your documentation.

A simple way to see what pages your customers tend to visit the most (and the least) is by using Google Analytics.

Source: gregcruce

You can find a lot of useful data there, and Greg Cruce, president of Venn Marketing, provides a good tutorial on his website on how to get to these metrics.

Another helpful metric you can track without too much hassle is the rating of your documents.

Similarly to the support tickets we discussed in the previous section, simple surveys inside the documentation can show you which parts are the most useful to the customers and which ones you should polish more.

For instance, Skype has a star rating system in their product documentation:

Source: support.skype

Although that’s already a very straightforward way to ask for customer feedback, you can implement an even simpler solution.

Take a look at how Freshservice tracks that metric:

Source: support.freshservice

Even with a binary choice like that, customers can provide you with helpful feedback, and you can measure the quality of your product documentation.

Those metrics we mentioned in this section are just a small part of what you can track.

However, they are easy to access and give you actionable information about the state of your product documentation.

Archive Outdated Doc Versions

When thinking about what to do in order to keep your product documentation in great shape, don’t forget to archive outdated versions.

As new versions of your product roll out, older ones will probably become obsolete. And their documentation will follow suit. Therefore, it is important to archive them.

The reasons for this are twofold. Separating older documentation from the updated one will remove excess clutter and reduce the chance of confusing your users.

But on the other hand, archived docs could still be useful for those users who are using older versions of your product, or those who simply want to remind themselves of some information they read in your documentation a few years or months ago.

So, what happens if you fail to archive outdated documentation?

Well, your customers could get annoyed, they could reach out to your customer support and use more of your resources by doing that, or—the worst case scenario—they could leave you and go to your competitor.

Source: Twitter

And they might not be shy to voice their frustrations, like this Twitter user above.

That reaction is understandable because by keeping outdated versions of your documents, you signal to your customers that you aren’t trustworthy and don’t care for their experience, which can have a negative impact on your whole business.

To avoid that snowball effect, you can simply notify your customers when they end up on an outdated documentation page.

Here’s how Apple does that with a clearly visible message for the users on the top of the main documentation page:

Source: developer.apple

As you can see, they warn customers that this is an archived page and provide a link to the new and updated one.

And if somehow a customer still ends up in one of the outdated sections, they can hardly miss another warning about it being obsolete.

Source: developer.apple

Archiving outdated doc versions will make using your product documentation easier for your customers.

There’ll be less chance of confusion, and the quality of your documents will always remain high.

In other words, keeping documentation fresh keeps it useful.

Conclusion

Keeping your product documentation in pristine condition requires a lot of work.

However, seeing how satisfied your customers are with it, how they spread the good word about your product and your company, and how your whole team prospers as a result will make it all worth it.

Therefore, if you regularly update your product documentation, assign someone to do so, encourage your team to contribute, review support tickets, track the performance of your documentation with metrics, and archive outdated documents, you can take a big leap towards having an excellent resource of product information.

Continue Reading