Technical writing in the world of SaaS

You need to document your software, but that should be easy, right? It’s just writing. Why not just have customer support do it in their spare time (haha)? Or maybe development should document it (they wrote it!)? Or should it be sales or marketing (they are good with words!)?

With the rise of the SaaS (Software as a Service) industry and explosion of software development, writing good docs has become an art form in itself as companies realize it’s not that easy to just write the docs.

What is software documentation?

Webopedia defines it as:

“Instructions for using a computer device or program. Documentation can appear in a variety of forms, the most common being manuals. When you buy a computer product (hardware or software), it almost always comes with one or more manuals that describe how to install and operate the product.”

Documentation is an oft-neglected area of software development and it has a reputation for being inscrutable to the common man. Definitions like this inform many people’s inaccurate view of software documentation. Does anyone really read the manual, and do manuals even exist for most SaaS software?

The rise of the SaaS docs writer

Wikipedia is a bit more up-to-date. It encompasses the different types of documentation writing that currently exist. In SaaS, there is software documentation aimed at other developers, and user documentation written for the customer. This has resulted in the role of SaaS end-user documentation writer.

Wikipedia’s definition reflects the fact that the workplace has been digitised, and we have many types of software that helps us perform our work. Lots of SaaS is business to business (B2B), requiring documentation for the end user, who is frequently a layperson.

The SaaS documentation writer’s profession is to write user-friendly software documentation as part of the product’s customer support.

That’s not to say that they don’t also write docs for the software itself. Including consistent, readable and up-to-date documentation is generally essential to the success of a project, as it allows multiple parties to enter into a project on an ongoing basis.

Whatfix offers a fantastic summary of all the different types of documentation out there. It covers not just the online help and user manuals typically associated with software documentation, but the vast variety of technical documents included in the full product and customer lifecycle.

Importance of software documentation

You never know when another developer might need to come in to work on your project, or whether your future self will know what you meant by a particular piece of code. The purpose of this type of documentation is to ensure other developers can obtain the information they need to work on the project.

Crucially, documentation can also be for users of the products (often customers) to help them understand how to use it. In the world of SaaS, it’s critically important to have good documentation that can teach customers how to use frequently complex products.

SaaS is often used by many people who are non-techie types. As a result, SaaS companies should ideally be laser-focused on writing quality docs for the end user. These docs should be interesting, compelling and user-friendly.

Even though product developers themselves can sometimes make great documentation writers, they are often so immersed in the product they see it from the point of view of the creator rather than the user. What’s more, it’s not always part of their job (or anyone’s job for that matter).

All too often, software documentation is sparse, hastily thrown together, outdated, or completely non-existent.

Cue the documentation writer 

Customer support is everything in the SaaS industry, but good docs writers are hard to find.

It seems that technically-minded writers are extremely rare, as writing normally falls under the umbrella of liberal arts. The problem is normally having writers who are experts in writing and not software, when in fact the act of writing is always intimately tied to the subject itself.

Software documentation requires product specialists who can both write and generally understand the software. Most documentation writers have excellent working knowledge of their products and are sometimes developers themselves.

Documentation writers are generally hands-on specialists who can write expert docs. They strike the delicate balance between having technical expertise, but also keeping the audience at the forefront of their mind.

There is sometimes a suspicion of those who can tie the two together, as if it is not really possible that empathy and technical know-how can peacefully co-exist.

Future of documentation writing

Documentation is an area of software development that sometimes suffers from a lack of priority. Historically, those contributing docs haven’t always been seen as part of the software development process itself, but all that is changing.

With groups like Write the Docs increasingly popular, documentation writer is becoming a recognised profession in its own right.

At the moment, docs writer is still such a new role that it’s shrouded in mystery and confusion. As a result, those not in-the-know have yet to discover how important this role is for successful software development and effective customer support.

New processes used at forward-thinking companies like Rackspace are catching on, such as treating documentation editing like coding pull requests. Creating documentation in real-time in response to the needs of customers is being pioneered by writers such as Bri Hillmer from SurveyGizmo.

The role of docs writer changes quickly, reflecting the nature of the tech industry in general. Docs Like Code is a book by Anne Gentle which is a must-read for any professional or aspiring documentarian who wants to learn more about their field.

Read more about the Write the Docs global documentarian community and how you can get involved.