​How to write documentation for SaaS

April 2018

Janetta Vacherand is a technical writer based in Auckland. She explains what SaaS is, and shares some tips on how to write good documentation for SaaS.


Hang on, what is SaaS anyway?

If you’re not writing for the software industry, you might not have heard of SaaS (pronounced sass). It stands for Software as a Service. SaaS is software that runs in the cloud and is accessed through a web browser. Customers create an account to subscribe to the service. Sometimes they pay for the service and sometimes it’s free. Think Xero for accounting software, Spotify for music, and Google Docs for office applications.

Traditional software is installed by the customer though a download page, or by the IT department of the business. It is the customer’s job to host the software, and back up the data. The software is a large one-off expense and requires periodic upgrades.

The cloud is a happy place

SaaS is a huge growth area. There are many SaaS startups, and software companies that have provided traditional software in the past are converting to SaaS. People love SaaS for many reasons.

  • Users love SaaS because they can access their software or service from almost any device – desktop, laptop, mobile. SaaS software is generally easy to understand and use, and free or relatively cheap.
  • Business customers love SaaS because they don’t have to manage software installation and upgrades, data backups or software security. All of the traditional IT management and administration tasks are dealt with by the SaaS provider. They also love it because it is subscription-based. Instead of paying a large one-off fee to get the software, users pay a monthly subscription fee. Software expenses are much easier to predict. Although private users are often reluctant to pay for software, business users are ready and willing to spend money on software that makes their businesses easier to run.
  • Software developers love SaaS because the cloud means that they don’t have to worry about lots of infrastructure issues like having a server room and running backups. SaaS companies still need to make sure that they find and manage a reliable and secure cloud service provider. However, once that is sorted they can pretty much get on and develop software.
  • Marketing and sales people mostly love SaaS. They like being able to give a potential customer a trial version of a product for free. Users create a trial account and have a month or so to play with the software, and see if it meets their needs. The downside is that because there is no large upfront payment for the software, the customer is less committed to making the software work. Customers can unsubscribe at any time, even before there has been enough time for the SaaS company to recoup the cost of making the sale.
  • Entrepreneurs love SaaS. There is a lot of support for SaaS startups through communities and conferences like SaaStr, and through investors that fund startups. In the same way that Tait Electronics has inspired electronics companies in the Canterbury area, Xero has inspired apps in New Zealand that integrate into Xero.

Let’s talk about conversion, churn, and onboarding

These are concepts that are critical in the SaaS world. They will help you understand why documentation is so important in SaaS.

  • Conversion is when a trial customer becomes a paying customer. This is very easy to measure.
  • Churn is when a paying customer unsubscribes. SaaS companies work very hard to reduce churn, and to investigate why customers unsubscribe. Churn is also very easy to measure.
  • Onboarding is the process of getting a potential user, trial user or newly subscribed customer up to speed with using the software. Effective onboarding is difficult to measure but is critically important for improving conversion rates and reducing churn. This is where documentation comes in. SaaS companies use videos and help centres in their onboarding process to get users up to speed on their software. Steve Moss, educational content creator from Workflow Max, a Xero company, says “supporting sales with their onboarding is a critical aspect of what I am doing as a technical communicator”.

Documentation and the bottom line: Onboarding

Since help documentation plays such a key role in onboarding, it contributes to profitability. Onboarding customers want Getting Started guides and videos, FAQs, and procedures. They want to be able to search for a particular topic and solve their problem. Having great documentation means that users can do all of that for themselves, without waiting for support, and they can do it at any time of day.

Documentation and the bottom line: A small support team

Call centres are expensive to operate, so many SaaS companies provide email or chat support which needs much smaller support teams. Part of what makes this possible is that many support queries are resolved by sending out links to the help documentation or video tutorials.

Simon Lampen, founder and CEO of Vinsight production and inventory software for the wine and brewing industry, explains. “We try to solve every support query by sending a link to the help documentation, rather than typing out a new answer. Sometimes we even create a new help page on the fly in order to be able to do that.”

SaaS is about the software AND the service

With SaaS, the software features are only part of the overall service to customers. Mikey Jarvis, Documentation Manager at Vend retail software, explains. “The software itself is just one part of what we offer to our retailers. Another part of our overall offering is the help content, training, and education. Our customer facing teams here at Vend work hard to make sure our retailers have all the help they need to succeed.”

Where does a technical writer sit in a SaaS company?

The correct answer is, of course, at a desk. However, where they sit in the organisational structure can vary. In SaaS, technical writers work closely with developers on new features, but they also work with customer support to provide help documentation for resolving support issues, and with marketing and sales as they onboard customers. Technical writers are typically in the user support team, or in the product team. Videos are usually made by technical communicators in sales or education teams.

What do I need to know to write for SaaS?

The good news is that you are probably ready to write for SaaS now. Most of the skills used in creating SaaS documentation are the same as for writing any type of user documentation. If you know how to structure documents, how to explain things to new users, and how to write in plain language, then writing for SaaS will be easy for you. Keep reading for some extra things to keep in mind for SaaS.

Work closely with support, sales, and product development

No matter who you report to in the organisational structure, you are writing for three main groups; user support, sales, and product development. The flow of information from product development is usually quite clear, and user stories will help you document new features. However, make sure that you also have good ways of getting feedback from support and sales for changes they want in the documentation, for example, new FAQs or areas that customers need extra help with.

Write in a friendly, conversational tone

Users really like a friendly conversational tone. Use personal pronouns like “you” and “we”. Use short sentences. Don’t use complicated words. Be friendly, but don’t be too casual or overfamiliar.

Monitor searches

Keep a regular watch on the words that users are putting into your help search box, and when searching your product in Google. You might want to modify your getting started section or FAQs as a result. Consider using SEO (Search Engine Optimisation) to ensure that your users get to your help documentation more quickly. Steve Moss from Workflow Max, a Xero company, explains: “Having a help system which is SEO-friendly is absolutely vital, because that is how so many users look for help”.

Also, make sure that you write with SEO in mind. Ensure that users get the right results when searching on everyday words, and not just the words you use in your product. For example, when users search on “Pay bills”, they should get the same results as if they searched on “Pay invoices”. Find out more about How to Search Engine Optimize (SEO) Your Help Documentation .

Make your navigation easy to use

Users want to solve their problems quickly and easily. To do this, you need a good navigational structure that allows users to easily scan headings and access subheadings. Most help systems have navigation in panels which contain collapsible folders.

If a user comes to your help documentation through a Google search, any page on your help system could be the first page that they see. Make sure that the navigation panel and search box are viewable from each page.

Use short headings

Users scan titles quickly, so use key words that tell a user succinctly what they will find in that section. Navigational panels mean that you only have a short amount of space for a heading, so you need to convey a lot of meaning in few words. Even the choice of verb form is changing. Many writers are using ‘Create demo’ rather than ‘Creating demos’.

Include video

Have you ever gone into YouTube to find out how to do something on your phone or computer? If so, you’re following a universal trend. Users like being able to watch videos on how to use software. If you’re making videos, try and keep them fairly short, and integrate them with your written documentation. Mikey Jarvis from Vend explains: “Some users prefer to watch video, and some prefer to read. We want to cater to both learning styles. The search takes the user to one place, and it’s up to them how they choose to learn”. Here are some examples of integrated videos from Vend and WorkflowMax.

Just keep in mind that videos are fairly time consuming to make, difficult to keep updated, and best done when you have a stable product. If the interface changes, it is fairly easy to redo a few screenshots. Redoing several videos is a lot more complicated.

Check formatting on devices

Although you will probably be writing your documentation on a desktop or laptop, your users might be using a mobile device to read it. Ensure that your documentation formatting shows correctly on all the devices that your users are using.

Keep an eye on chatbot technology

Chatbots aren’t yet commonplace in support in New Zealand, but artificial intelligence is making huge advances in online support, and chatbots are getting more human-like. No one is expecting chatbots to be able to sort out complex queries, but for simple queries, chatbots will become part of the support offered to users. They will send out links to your documentation, and possibly integrate your documentation into their responses. If you’re interested in learning more, have a look at Rebooting with bots: The future of (assisted) technical documentation .

Learn from the masters

Many SaaS companies make their help documentation publicly available. Check out the help centres of these New Zealand SaaS providers:

Have fun

Janetta Vacherand

SaaS companies work hard to attract good talent and try to make the office a fun place to be. It isn’t uncommon to see Xboxes, table football, and free drinks in SaaS workplaces. Fraedom, Orion Healthcare, Streamliners, Vista Entertainment Solutions and Xero employ teams of tech writers that document SaaS products in New Zealand. Expect a fast pace, lots of change, and lots of fun!

Further Reading

Janetta Vacherand