SaaS Product Documentation Mistakes to Avoid Doing

Although product documentation can be a great help to your business, this is only true if the documentation is well-made.

You wouldn’t enjoy reading a map with inconsistent color codes and varying distance ratios, would you?

It would be frighteningly challenging to read and likely simply end up confusing you more.

The same principle applies to product documentation. For these texts to be beneficial, there are certain pitfalls you must avoid and guidelines you should follow.

Luckily for you, this article outlines this information as we take you on a tour of the most common SaaS product documentation mistakes.

Having a Disorganized Structure

Imagine your user is examining your API documentation, searching for how to perform an idempotent request.

They know the information is there but can’t locate it. They spend half an hour until they find it and stay an additional 30 minutes in the office to make up for lost time.

Now imagine if your documentation had been more structured to begin with.

The user would have been thrilled to have found the information immediately and saved themselves a significant amount of time.

This is why it’s essential to ensure your product documentation is organized, as most users will attest to:

If you want to keep your users happy, you’ll focus on optimizing the structure of your product documentation.

Decibel is an excellent example of a company that has realized the value of well-structured documentation. Take a look:

Their articles are grouped into logical categories and have a clear layout, which significantly facilitates navigation.

Furthermore, once you enter a category, moving around inside that grouping is easy. Let’s explore the Account Settings section:

A straightforward guide on the left-hand side outlines the category’s other articles.

With this structure, users can quickly investigate the information that interests them and, at a glance, discover other pertinent articles.

Another advantage to organizing your product documentation well is that you’ll reduce the number of support requests.

Research has revealed the following:

If your customers can’t locate the answer independently, their next stop will be your support center.

That could easily result in many calls and place a considerable burden on your colleagues.

However, by structuring the documentation well, you ensure that your customers are able to find the information they need on their own, freeing up time for the support team to focus on more complex issues.

If you’re unsure how to begin organizing your documentation, there are four main approaches you can adopt, outlined below:

With the first method, you’d likely position articles on "onboarding" or "getting started" in one of the principal positions, whereas sorting documents by difficulty will place the most straightforward solutions first.

The workflow-based approach relies on standard work processes that will be familiar to most users, and the ‘categories’ strategy gathers together similar topics under one umbrella term.

Whichever approach you choose, the structure is guaranteed to be easy to navigate, an essential characteristic your users will thank you for.

Using Complex Language

Although using complex language might seem like the optimal way to show off your expertise and tout your company’s proficiency, this approach habitually leaves your users bamboozled as opposed to overawed.

How many tries did it take you to read (and understand) that sentence?

Elaborate sentences and literary jargon seem appealing initially, but they’re likely to frustrate your users.

They’ll probably have to re-read sentences and look up vocabulary they’re unfamiliar with, which doesn’t make for a pleasant experience.

Instead, you’d do well to compose the documentation in plain, everyday language.

This makes the text easily digestible, ensuring your readers understand everything on their first read-through.

For example, here’s Netflix’s product documentation:

The language is exceedingly simple, especially the “Can’t Watch” column.

Instead of naming it "Common Bugs" or "Troubleshooting", the articles are grouped according to their core issue: that customers are unable to watch Netflix.

Any user with a viewing roadblock knows precisely where to solve their problem.

However, there are several approaches when composing product documentation titles, outlined below:

Closed questions target specific issues such as “Can I reset my password?”

When you rephrase this same concept as a problem, it becomes “I can’t reset my password.”

Moving on to the “how” approach, the article would read “How to reset the password”. Finally, the descriptive method would simply be “Resetting the password”.

Whatever method you choose, you’re on the right track—they all use plain language your readers will undoubtedly understand.

It’s also advisable to continue this philosophy in the article’s body. Here’s an excerpt from Netflix’s article on resetting the password:

The sentences are generally short, snappy, and straightforward. The longest sentence is only 21 words, yet still broken into two clauses with a comma.

This brevity makes all sentences easily readable.

Furthermore, the verbs are primarily in the present tense and imperative mood. This simple verb form is significantly preferred to more complex grammar, such as conditional clauses.

The Hemingway editor is an excellent resource if you want to follow these guidelines.

This online tool assesses your text’s readability and offers suggestions to make the language simpler and clearer.

Here’s what it looks like:

The app immediately highlights difficult-to-read sentences in yellow and red, and suggests improvements.

With this tool, you’ll be composing straightforward and clear articles your users can easily read in no time at all.

Not Including Visuals

When reading a novel, being faced with a vast wall of text is a given. This is rarely an issue, as novels are creative, engaging works that naturally grab the reader’s attention.

However, you’d be hard-pressed to say the same about product documentation.

Dense with information, product documentation’s primary purpose is to educate its readers.

Although the written word is essential for this aim, visuals can also significantly facilitate knowledge comprehension. Consider the statistics below:

In general, it’s much easier for the human brain to process information if it’s in a visual form as opposed to simple text.

For example, take a look at Mailchimp’s documentation on adding a poll or survey:

This section explains the first steps towards creating a poll in a Mailchimp marketing campaign, and multiple images have been included to help the reader understand the process better,

If the instructions to click “Edit Design” hadn’t included a screenshot of the button’s exact position, it might have taken the user much longer to find it.

However, this visual gives them precise information on the necessary next steps.

Furthermore, the visual helps break the text up a little bit.

Without this image, there would have only been text until the more complex portion (the syntax behind the poll merge tags), which can easily overwhelm the reader.

By including the image, the reader has a small rest before moving on to the details.

Mailchimp has done one more thing right with this excerpt: they’ve included color in their image. Colors are proven to be beneficial for knowledge retention, as research has proven:

Color both increases learning retention and improves attention spans—a trick that especially comes in handy with product documentation.

While you can always highlight words and change the color of the text, the easiest way to include color in your documentation is to simply insert visuals (be it images or videos), which are often colorized by default.

After all, you’d be hard-pressed to find a black-and-white photo nowadays.

On the technical side of including visuals, you’d do well to invest in a documentation platform, as they significantly facilitate embedding images and videos.

For example, this is how it works with Archbee:

‍The editor allows three easy methods for inserting images and two simple processes for including videos.

These shortcuts effortlessly elevate your product documentation with visuals your readers will greatly appreciate.

Neglecting to Proofread

No one wants to read documentation explaining how to use their sotware, nor will they enjoy read it.

Does the sentence above make any sense to you? You can grasp its general meaning, but the misspelling and the incorrect verb form likely hindered your comprehension.

This is a serious downfall, as your documentation should be as clear as possible for your users.

Besides, these errors can paint your company in a bad light—few things are deemed more unprofessional than routine spelling mistakes. Jo Burrows has quipped about this:

Luckily, however, there are easier ways to proofread. For example, Grammarly is a writing assistant tool that will catch all of these grammatical and spelling mistakes.

Here’s the resource in action:

If we apply Grammarly to the previous erroneous sentence, the tool highlights the incorrect spelling and wrong verb form.

It also immediately corrects them so the document can be edited in a heartbeat.

However, you don’t want to constantly rely on Grammarly, as the tool can’t catch every mistake.

Just think of date formats. Although both 04/10/2022 and 10/04/2022 are valid dates, they refer to entirely different days and months in different parts of the world.

However, Grammarly can’t tell if you’ve employed a suitable format.

For this reason, it’s also a good idea to consistently refer to a style guide while writing, as this document will instruct you through such details.

Here’s what Google’s style guide has to say:

Google circumvents this issue by requiring that its employees write the dates in full.

Therefore, constantly referring to the style guide should prevent any mistakes and maintain a consistent writing style.

However, there’s often no better editor than a fresh pair of eyes. If you have a detail-oriented employee, it’s well worth sharing the document with them so they can give the text a once-over.

This is why a collaborative tool such as Google Docs pays off, as it’s easy to share documents among users.

All you need to do is share access, and your colleagues can easily proofread texts. Here’s what it looks like:

After sharing your document, the newly added editors will have access and can proofread and edit the text in the same document, streamlining collaboration.

With one extra colleague examining the document, there’s much less chance of grammatical errors.

Not Updating Documentation With the Product

Writing product documentation doesn’t have a definite end date. Instead, as your software develops, you should also update your documentation in tandem.

That way, you’ll keep the documentation up-to-date and avoid any negative customer experiences.

Imagine your customer is using your text editor but can’t change the font. They browse the documentation, but the text hasn’t been updated since 2018.

The article is useless, they’re still stuck, and they’ve lost time.

The entire experience is aggravating, and the user will lose faith in the company if it happens often.

Worst case scenario, they might even abandon the software for another solution and contribute to your customer churn rate.

Customer churn is defined as follows:

In other words, high customer churn means customers are abandoning your company in droves.

Inconsistent, out-of-date documentation is one factor that will add to this sobering metric, so you’d do well to update your product documentation continuously.

On the flip side, if you maintain relevant product documentation, your users will greatly appreciate this and are much more likely to stay.

From there, it’s been proven that as customer retention increases, your profit also rises:

The more customers you keep, the more your profit will increase.

Your users’ satisfaction is the key to these results, and an easy method for ensuring this is to edit your product documentation regularly.

Furthermore, you’re also likely to earn their trust with this approach. If your documentation is constantly relevant, users will recognize your attentiveness and appreciate your work ethic.

They’ll see you’re a company they can rely on, which is a vital attribute to boast in the current climate:

By staying on top of your documentation, you’ll prove to your customers your product is trustworthy and that you can provide them with a positive user experience.

Archbee can help you towards this goal through its recurring document verification feature.

With this feature, a particular team member is assigned a document—they will receive automatic, periodic notifications to check a document’s content.

This can be as often as every week or as rare as every three months. The video below showcases the feature:

Source: Archbee on YouTube

By sending out these automatic updates, your team members can maintain the documentation through routine checks, and you can rest assured your records will never go out of date.

Conclusion

If you want to write quality product documentation, there are several dangers you must steer clear of to avoid a negative customer experience for your users.

For starters, ensure the documentation is well-organized so your readers can easily find the information they’re looking for.

Furthermore, do your best to employ plain, simple language and plenty of visuals for the best comprehension results.

Finally, ensure you proofread the documentation at least once and consistently update the texts as your software evolves.

Follow these guidelines, and you’ll be sure to provide a great user experience for your customers.

Try Archbee's full range of features with our free 14-day trial.