An Optimal Outline for B2B Software/SaaS Products

I always recommend the following outline. It addresses the needs of all user groups, from power users to sporadic viewers.

Remember, that a technical documentation is more than just a description of buttons or APIs. Below I introduce a few sections that may seem less obvious to include but add value to your product.

Introduction

The introductory part has a few goals manifested in the following sections.

Feature Overview

A feature overview should provide a short soft-selling section about the main features and advantages. It may be similar to your product page but more detailed. A technical documentation usually has a more modest design and allows you to focus on the content. This section also prepares users for what they can expect to find in the documentation.

For instance, Amazon EC2 features overview is a short recap of its advantages.

Prerequisites

Believe me, it is very annoying to find out in the middle of the installation that you cannot use the application because you need this and that. Even if the preparation takes time, by informing readers about it in advance, you increase the chances that they complete all steps. No surprises mean more trust and motivation.

A good example, well structured and containing only essential information is the Visual Studio Code requirements article.

Main Concepts

Concepts are neither workflows nor features. They are bridges between the former and the latter.

Broader Context

By providing a short “theoretical” part, you help users to better understand the advantages and possible implementation of your product.

This is often relevant for the high-end B2B products engineered for companies going through a digital transformation.

For instance, if you offer a testing automation tool, you may try to cold pitch customers that never used any automation before. Some of the executives may need to comprehend first what automation actually is since it has become quite a buzzword on its own.

By providing, let’s say, a chapter on the main testing automation frameworks, you can show them how to approach automation at best in their particular case. Look at this GUI testing guide by Ranorex. You are showing your customers they have a choice, and that you are helping them to make it cleverly.

Glossary

For business users, you may additionally include a glossary with particularly tech-savvy terms. Keep in mind that a glossary makes little sense as a standalone section. You should link to it from everywhere in the main documentation each time you mention a certain term.

Although a very short but illustrative example is the Virtual Box article on used terminology.

Architecture

As in the previous case, this section may be superfluous for an application created for end consumers.

However, if you offer a SaaS platform or a completely new technology for developers, such as IaaS, you will need to explain how your product works in the background before someone can use it.

Look at the Kubernetes documentation. It outlines the architecture and its components since barely any other technology is based on similar concepts.

Of course, you do not need to give away too much information that would allow someone to replicate your business model. Kubernetes is open source and many companies offer it as a managed service. They basically take the source code, modify it to some extent, deploy it in a cloud, and offer it as a subscription.

Getting Started

This section guides users through the setup and through one most common workflows.

Registration

Although most of the time user registration is quite a straightforward procedure, take your time to describe it. You need to inform them about possible “pitfalls”. For instance, sometimes, an SSO login won’t allow new users to change their names later. Or the registration involves certificates that users need to save in a certain path on their computers.

Example: Jfrog Artifactory’s article on MFA authentication for new users.

Installation

I almost marked it as optional since many of my customers either offer a SaaS platform or an application that is easy to install.

Nonetheless, if you sell a technology that requires installation from a command line tool, you must provide all CLI commands that users need to run to start using your tool.

Do not forget that different users may prefer different installers. Have a look at the Jupyter Lab installation guide here.

A Very Common Workflow

Especially for the single-purpose tools, niche tools, and low-level and middleware applications, I highly recommend to include the first how-to guide right in the beginning.

Low-level and middleware are kinds of software that end users never see. The target group for both types are developers and DevOps or business users with at least some technical background.

It can be very dry and aimed at an experienced user. Those just need to be able to start quickly. Optionally, add a link to a detailed feature overview for all the others.

Sourcetree documentation goes straight to the four main workflows and explains the rest in the general knowledge base. Another good example is Quay documentation that brings together a few main CLI commands to use in one article.

Optionally: License/Subscription Plans

If your offerings differ not only quantitatively but also qualitatively, do not forget to add a detailed explanation and refresh it accordingly.

For instance, if a business plan only means more storage then it’s not worth a separate article in the documentation. But if users get a storage space only starting from a certain plan, it may influence their strategy for integrating your tool into their existing workflows.

In the end, it influences their buying decision. Google Cloud has a pricing page that looks like documentation since calculating costs is taken seriously by the provider and is in fact quite tricky.

GUI/Features: Detailed Overview

Here, we are talking about pointing users to certain buttons, tabs, etc., in the user interface. Naturally, the GUI features must be grouped in a manner that allows users to perform actions in a pre-defined and convenient for them sequence.

You can keep this section slim, as Apache Zeppelin chose to. I recommend to cover pretty much every GUI element, even if the usage seems obvious to you.

There are a few options for not making this section boring.

In the case of WordPress, a GUI overview is a mixture of concept overview, main workflows, and features overview. It describes in one article, for instance, what blocks are and what you can do with them.

On the contrary, Wix, another popular website builder, does not provide a separated documentation. It publishes guides for the most common workflows in its blog.

If you look at the Harbor documentation, which is a low-level developer tool, you will find a GUI overview segregated by main workflows and levels of permissions that the reader has: developer (user) versus a system administrator.

Main Commands/Language Reference

Quite obviously, if your tool requires using a uniquely developed syntax, you need to explain how to communicate in it. For instance, Salesforce Einstein Analytics SAQL reference goes through all operators, statements, and functions that are the basic elements of its query language.

A more complex query language GraphQL has an even more detailed documentation. It teaches not only to write queries but also to interpret the returned results.

Docker Hub documentation is structured in a different way. The basic commands are spread all over it. The reason is twofold. First, the commands are too simple to cause difficulties with memorizing them. Second, their simplicity makes them look “mysterious” outside of the proper context. That’s why code snippets with certain commands are integrated into the knowledge articles that describe the most common workflows.

Integrations

Nowadays, a rare application is used in isolation. On the contrary, integrations became an important selling proposition and almost a must-have.

Even if integrating your product with another is straightforward and simple, remember the traffic-generating power of your documentation. Connecting Asana with Slack is easy but is also a good insight into the functionality of both tools that may manage to convince a few more customers who happened to look into the documentation.

Indeed, for API integrations and complex workflows, you have to provide this part otherwise users won’t see an advantage in your product.

For many SaaS platforms, such as Datadog, integrations are the foundation of their business model. Datadog’s core task is to collect and process application monitoring data. That’s why the integration part of its documentation looks gorgeous: check this Amazon EC2 integration guide. It is only one of the dozens more!

User Guides: Most Common Workflows

In this part, you should describe the core features of your product in the context of the most common use. Do not simply describe buttons in the order of their appearance in the user interface. Instead, you should provide steps for solving the main users’ problem.

This section can host multiple articles.

Indeed, the functionality of your tool must be developed in these most common workflows in mind. If it is not, it can be difficult to fix it through a brilliant documentation. The whole thing must be the other way around: the interface of your product should follow the most common use cases.

For instance, GitHub’s Hello World user guide covers all essential steps for managing a source code, whereas the Forking Projects guide describes how to generate a personal copy of an open-source project. Both guides mention the same feature – making pull requests – but in a different context.

Troubleshooting

Hiding weak points of your product won’t prevent you from losing users. But helping them will. Sometimes, it is not even necessarily the fault of your product. It may be a glitch on the third-party side or some incompatibility. It may be a generally complex workflow prone to errors, such as working with datetime fields in a data analytics tool.

Microsoft had the courage to create a complete documentation dedicated only to the troubleshooting of their products.

The first thing to include are known bugs. The second big source of information are cases/tickets in your customer support system.

Release Notes

Atlassian keeps release notes for all JIRA releases starting from its launch. It allows developers to understand the path of its evolution and facilitates troubleshooting since you can track a troublemaking feature back to its release and, if you want, revert your software to a more stable version.

Release notes inform your power users about the newest features. Those who already thoroughly studied your documentation, can quickly make themselves familiar with the new functionality and do not have to search through the docs again.

Migrations

Sometimes, your last software release draws a line under an evolutionary phase creating a completely new look and architecture of your product. Such rebirth may cause headaches for some of your power users.

Thus, remember to describe how to move safely from the old version to the new one, as Stoplight documentation does here.


I hope that these dry instructions can help you in building your own knowledge base. Still think you need a technical writer?

Feel free to give me a call:
+49 177 490 16 59

or drop a line to discuss your needs:

    Stay healthy!

    Leave a Reply

    Your email address will not be published. Required fields are marked *