7 Common Mistakes to Avoid Writing SaaS Product Documentation

saas product documentation mistakes

Documentation is absolutely essential for attracting and retaining customers to your SaaS product – but a surprising number of companies aren’t getting it right when it comes to enabling customers to help themselves.

This is a huge problem, as self-service is expected by 70% of your customers and companies with a self-service strategy retain 68% more of their customers year on year.

Common SaaS Product Documentation Mistakes to Avoid

Avoiding these 7 documentation mistakes will put you ahead of the curve, and make your self-service strategy more effective.

1. Documentation out of sync with the product

There’s nothing worse than writing your SaaS product documentation and finding that it’s out of step with product development.

Features that you documented have changed or are no longer there. Interfaces have changed or copy is different. The documentation doesn’t match up to the product anymore.

The best way to keep on top of this problem is to have your docs as close to the source code as possible. Even if a full-blown docs like code approach doesn’t work for you, consider integrating your technical writers with your development team as closely as possible. Don’t let a product ship without documenting every feature properly.

If you think documenting all your features is a waste of valuable time, imagine your customers churning in droves because they don’t understand how to use your product.

Screenshots, while useful, are yet another area of your documentation that can become out-of-date really quickly. Your product is constantly evolving and UI/UX changes constantly, it’s important to keep your screenshots in sync.

Schedule regular reviews of legacy documentation to check what updates you need to make.

2. Documentation structure is not optimized

When launching a brilliant SaaS product, you need to spend a lot of time thinking about how you’re going to structure your documentation.

Categories, subcategories, menus and articles must be easy to navigate and guide users to the correct destination. At first glance, don’t reveal too many levels down as this could be overwhelming.

At the same time, make it clear there is lots of information contained within your knowledge base.

To put it succinctly, your information architecture must be top-notch. View your documentation from the perspective of your user and what perspective they might have on first encountering your help portal.

Follow technical writing methodologies like DITA (Darwin Information Typing Architecture) which is an open source model for XML – specifically the principle of ‘content reuse’. Write your content in chunks that can be repurposed in different contexts and formats to make the most of your resources.

3. Too many details

Users want your documentation to be succinct and to the point. Most pieces of content should focus solely on helping them to complete a specific task, unless it’s documentation for technical specs or listing features. Then, it pays to be comprehensive.

Understand that your users are probably well-educated, and there’s no point in explaining how to do something screenshot by screenshot. Make a calculated judgment on what level of details that you need to include to get the job done.

This entails having a clear picture of your typical user, or several different personas. In a SaaS product not aimed at developers, your user is likely to be digitally savvy but not necessarily too technically minded.

Hold their hand – but not too much.

4. Spelling mistakes, typos and incorrect grammar

Even though it might seem trivial, make sure you address any copywriting mistakes such as spelling, typos and grammar. If you don’t, this runs the risk that your end users will lose confidence in your product and probably undervalue or misjudge the value you can deliver.

This is because basic writing mistakes make it look like you don’t care about your documentation enough to proofread it – or worse, that you don’t understand you got it wrong. Professional companies must have flawless copy.

While technical writing has evolved to the point that we don’t have to stick so very strictly to grammar rules, it’s important to be intentional and consistent about what you write. If you use the Oxford Comma, check that you always do this.

Syntax plays an important role in communicating the meaning of your content – the arrangement of words in your sentences. Consider this quote:

“John and Paul had cats, and he picked his up.”

Who picked up which cat? The syntax is not helping us to understand the meaning of the sentence.

You could say:

“John and Paul both had cats, and John picked up Paul’s.”

But then you don’t know what number of cats each of them has. It’s still ambiguous.

A better version would be:

“They each had a cat, and John picked up Paul’s.”

5. Missing a table of contents for long articles

If you publish a very long article in your knowledge base, this should really be presented as a collection of shorter articles. Your table of contents should offer a breakdown of the content contained within your article, and ideally hyperlink to each specific section.

Using a table of contents provides a better user experience and makes it easier to navigate to get to the information you need.

Even if users are using the search function to find content, it’s not much good if this takes them to a particularly long article and they still don’t know where exactly to find the correct information.

While you can place the burden on them to use CTRL + F, it’s much better if you use a table of contents to signpost users.

6.  Too much jargon or in-house terminology

Specialised jargon can be a huge barrier to newcomers trying to understand your docs. Your documentation has to be as accessible to new users as for seasoned pros or your risk alienating them.

It’s easy to assume that everybody uses the same language as you and is operating under similar assumptions – especially when you’re incredibly immersed in the product. Nothing could be further from the truth, and yet it’s a common pitfall when writing product documentation.

Choose common words that are easy to understand over jargon. If it’s a button, call it a button – rather than ‘upload launchpad’.

Simplicity is beauty in writing documentation. If you must use specific terminology, consider including a glossary or defining the terms used within the article body.

7. Lack of correct highlighters in the articles

Formatting your documentation to highlight key information can vastly improve readability.

For example, you may want to draw attention to warnings or code snippets because these will be very important to some users.

When it comes to errors, warnings, key information and code snippets etc, make sure they are all visualised correctly and consistently.

This really helps your users to seek out important information in what can be quite lengthy documentation. In the case of a warning (“pressing this button will delete all your data”) making sure your users notice it can be absolutely crucial to product success.

Your highlights should stand out in an alternative colour, although a strong choice like red may be too alarming. Depending on your colour scheme, green or blue may be enough to draw attention to an element.


View these ‘mistakes’ as areas for improvement, and a sign that you have produced a good foundation for your documentation.

Make sure you:

  • Keep your documentation in sync with the product
  • Optimise your documentation structure
  • Include only essential details
  • Eliminate typos, and spelling and grammar mistakes
  • Include a table of contents if necessary
  • Avoid jargon or advanced terminology
  • Use correct highlighters for key information

We all wish our documentation could be perfect all the time. Although that’s not always possible, we have to watch out for those common pitfalls in writing documentation.

To learn more about product documentation please follow: https://document360.io/blogs/untapped-power-product-documentation-marketing-saas/