Documentation: The under-appreciated hero of SaaS

Documentation, more often than not, is an afterthought for many SaaS businesses. But when given focus it deserves, it can be a highly-scalable customer success machine capable of stopping churn in its tracks.

  • Sweating the details on your product’s visual design.
  • Tackling complex technical challenges at scale.
  • Building a world-class sales team.
  • Putting together a comprehensive library of documentation.

One of these things is seen as considerably less “sexy” than the others. I don’t need to tell you which.

Documentation is more often than not an afterthought for many businesses; a checkbox to be ticked once the core business functions are up and running smoothly. In some ways, it’s understandable — there are often far more compelling priorities with immediate, quantitative benefits. But I’m here to convince you that documentation can actually be a make-or-break competency within your business that can make the difference between scaling success and crippling churn. So let’s get started.

Why is good documentation so critical?

Ever heard this statement before?

“A well-designed product shouldn’t need documentation. It should just be obvious.”

That assertion may well be true in the consumer space. Nobody expects to read the manual for Spotify (although my recent attempts to use Snapchat leave me wishing for a quickstart guide). But B2B software is big, and can cover a variety of use-cases. Some advanced functionality will just never be completely intuitive — and that’s fine.

For a B2B SaaS business, the documentation is the additional line of support that scales infinitely. One how-to guide can be served to millions of customers at almost no incremental cost. The more of your product’s functionality that can be covered by good documentation, the more scalable your business.

For developer-focused products (i.e. API-based SaaS), documentation is not an option. API documentation is basically a part of the API itself. One without the other is essentially useless. In fact, for such products, developers will often judge the product by your API documentation. It’s the first port of call after the landing page — we’ve seen evidence of this on the ChartMogul site.

Look at the first item in Twilio’s navigation menu:

Twilio knows the importance of documentation for its developer-focused products.

What great documentation looks like

Write The Docs is a global community focused around technical writing. They outline an excellent set of principles for documentation that address every aspect:

“In general, documentation should be…”

  • Precursory: Begin documenting before you begin developing.
  • Participatory: In the documentation process, include everyone from developers to end users.

“Content should be…”

  • ARID: Accept (some) Repetition In Documentation.
  • Skimmable: Structure content to help readers identify and skip over concepts which they already understand or see are not relevant to their immediate questions.
  • Exemplary: Include (some) examples and tutorials in content.
  • Consistent: Use consistent language and formatting in content.
  • Current: Consider incorrect documentation to be worse than missing documentation.

(The site goes on to outline more principles, read the full guide.)

Fortunately for us, there are a number of SaaS businesses doing an amazing job at documentation in 2017:

Stripe’s documentation contains interactive, sandboxed elements for you to test functionality:

Some API documentation (like ChartMogul’s) offers code samples in the language of your choice:

Web design and development platform Webflow created Webflow University, with a series of courses featuring video lessons:

How we’ve improved documentation at ChartMogul

Identifying and filling gaps

One of our first steps was to look at the top search phrases in our Help Center, and identified trends in what people were looking for. This immediately gave us some “low hanging fruit” in the form of common searches related to easy-to-solve problems in the product that we didn’t have docs for. These common searches represent gaps in knowledge which are sometimes amplified by a poor or confusing experience in the product.

Plugging gaps with targeted, easily-discoverable documentation gives a vastly-improved experience for users. You’ll see a measurable impact on support tickets in filling these gaps.

Focusing on proactive vs. reactive documentation

It can be useful to think about two different categories of documentation:

Reactive documentation: Where the user has a problem or question and seeks help themselves. This usually results in a search in the Help Center. If this process fails, it may result in a query to our Support team and the creation of a ticket.

Proactive documentation: Where the user consumes educational content as they are onboarded into the product, and throughout their journey as a user. This kind of documentation doesn’t rely on the user actively seeking it out.

Clearly, in an ideal world, the vast majority of our documentation would be proactive. This way we don’t have to wait until the user has a problem, and we have much more control over the educational journey with our product — resulting in an altogether better experience.

Unfortunately this ideal world doesn’t exist, and the user will never have all the knowledge they need to solve every problem in our product. But using certain tactics it’s possible to shift a massively-reactive documentation library to a much more proactive one. Here’s how we did that:

Bringing documentation closer to the product

Eliminating friction with documentation is critical to its success. Finding documentation can already be an arduous task for users, so the slightest bump or point of friction can cause them to give up. In a scenario where they’re already likely to be confused, or even angry — well, you can imagine the outcome.

Proactive content (mentioned above) works best when it’s as close to the use case product it’s addressing as possible. For us, making small snippets of documentation easily accessible within the relevant part of the product has really helped smooth out the education process.

The ChartMogul product contains tooltips with useful content and links to relevant resources.

The result: Reversing the growth of “tickets per customer”

The structure and discoverability in the early days of ChartMogul was bad. We knew this for some time before putting serious effort into re-launching our Help Center.

We rolled out a comprehensive redesign of the Help Center, featuring:

  • Drastically-improved search (we used Algolia for this). We also put a greater emphasis on search – it’s now front and center in the design.
  • Complete re-categorization of the content, based on what we’d learned about the previous structure
  • A visual redesign, for better alignment with our brand and an overall more pleasant experience
The improved search experience in the ChartMogul Help Center, enabled by Algolia. Try it out for yourself!

The results were surprising. We expected some effect on our support process, but what we saw was an immediate and significant change in the growth rate of our “tickets per customer” metric.

As our customer numbers grow at ChartMogul, keeping “tickets per customer” under control is more and more critical for scaling our support team. Clearly better documentation looked to be a prime candidate for positively affecting this, and we weren’t wrong:

As the chart clearly shows, our ticket volume (which was slowly growing) saw a sharp decline after we launched the new Help Center in June. While our total change in customers was around +20% from March to July, the total change in ticket volume was -10.5%!

This cemented our belief that investing in improving documentation was going to be a key part of our ongoing customer success strategy at ChartMogul. We’ve since implemented many more improvements and created initiatives to take this further.

Steps you can take to invest in documentation

There are many small steps you can take in your business right now, to get on the right track towards giving documentation the attention it deserves.

Short term:

  • If you have the data, take a look at the common search terms for your help center, as mentioned above. These should show you the biggest pain points for users.
  • Un-publish any documentation that’s inaccurate or out of date! This is arguably worse than having no documentation.
  • Get an independent review of your docs. This could be someone in your business who’s not as close to the product as your technical and product teams, or someone outside of the business. This will highlight the obvious areas where you’re causing friction for users, and should lead to some simple fixes.
  • Go and become acquainted with Write The Docs. Really, it’s an excellent resource and community.

Longer term:

  • Bring your documentation into your product, for a smoother educational experience.
  • Design an educational curriculum to accompany your product onboarding. Think about the logical steps and order in which users should learn the different parts of your product.
  • Hire a technical writer to put documentation front and center. Or at least having a person within your company for whom documentation is the primary responsibility.

What have you learned about documentation in your company? Is there something smart you’re doing to educate your customers? We’d love to hear about it — drop a note in the comments below!

Ed Shelley

Former Director of Content


api customer success documentation saas