At Replicated, we believe that documentation is part of the product. This means that a feature is not considered done until the corresponding documentation is also published. Not only does this help us keep the docs up-to-date when new features are released, but it also gets everyone on the team (technical writers, product managers, developers, etc) involved in writing, testing, and publishing the docs. As the documentation manager at Replicated, I know how important this level of collaboration is to delivering docs that are as accurate, complete, and clear as possible.
We’re passionate about documentation because we understand that it is crucial for customer success. Particularly for self-hosted software, users will heavily rely on documentation to get the information they need to install, configure, manage, and troubleshoot an app. For this reason, your docs can make or break the user experience for your app.
Of course, getting started with (and maintaining) your docs isn’t easy. Particularly for smaller teams that might or might not have a dedicated technical writer, it can be hard to know where to begin. In this blog, I’ll run through some key considerations, examples, and templates to help you get past the writer’s block and on your way to publishing great docs for your app.
Setting Up a Docs Website
Product documentation websites tend to be static sites, where the same content is served to all users. This means that the site uses server-side rendering of HTML, CSS, and Javascript files, rather than needing to query a database to render client-specific content. This makes static sites relatively lightweight, fast, and easy to maintain.
Static site generators (SSGs) are a tool that can be used to build static websites from text files, such as Markdown or AsciiDoc, and templates. Some popular SSGs include:
- MkDocs
- Docusaurus (this is what the Replicated docs site uses)
- Jekyll
- Hugo
When choosing a static site generator, consider the language and frameworks that you want to use (Markdown, AsciiDoc, MDX, and so on), the completeness and helpfulness of the available documentation for the SSG, and the existing community for the SSG.
Beyond choosing your SSG, some other considerations to keep in mind when creating a docs website include:
- Consider making the repository where you keep your docs content and website files public so that you can accept edits from users both inside and outside your company. The replicated-docs repository in GitHub is public, and users are able to open a PR or issue in the repo by clicking Propose Changes or Provide Feedback buttons that are displayed at the bottom of every page on the site:
- Provide a way for users to search the content on your docs site. Many SSG include support for search out-of-the-box or through a configurable plugin.
- While static sites are already helpful for SEO (search engines can more easily discover the content from statically generated HTML pages), you can also help improve SEO by always including alt tags to describe images, using semantic HTML, and writing clear titles, headings, and content in each page. Your SSG might also publish docs with suggestions for improving SEO, like this page in the Docusaurus docs. Just be careful not to let SEO drive all of your content decisions; this can lead to poor quality content that is less useful for the human users of your docs site.
Using a Style Guide
Style guides provide content guidelines in areas like language and grammar, punctuation usage, formatting, and more. The goal of using a style guide is to ensure that information in your docs is clearly communicated to a specific audience, using a consistent style and voice. This makes it easier for all users to read the docs, reducing the opportunities for confusion that can be caused by content irregularities.
Rather than reinventing the wheel, consider adopting one of the many existing public style guides. For example, the Microsoft Writing Style Guide and the Google developer documentation style guide are helpful resources that explain general principles and specific formatting guidelines that you can apply to your own docs site. They cover topics like accessibility, writing to an international audience, how to use common organizational elements like lists and notes, and more.
Organizing Your Docs
Documentation websites have a panel on the left side of the screen that organizes all the topics (this is referred to as a sidebar or table of contents). All docs sites will organize content in the sidebar slightly differently depending on the given software product and audience. However, in general, it can be helpful to include higher-level sections that speak to common tasks that users will complete (like installing or managing an app).
For vendors that distribute their app with Replicated, some sections to consider adding to your sidebar include:
- Getting Started. At the top of the sidebar, include a section that provides introductory content like an overview of your app, FAQs, or beginner-friendly tutorials.
- Installing. Add a section for your installation docs, which might include an overview of the different installation options, prerequisites, requirements, information about how to configure the app, and procedures for each installation method that you support. (I’ll talk more about installation docs below.)
- Managing. Add a section with procedures on managing the app and/or the cluster where the app is running. For apps distributed with KOTS, this could include anything that users do from the KOTS Admin Console, like backing up and restoring with Snapshots, synchronizing a license, updating configuration preferences, adding or removing nodes in an embedded cluster, and more. For an example of this type of content, check out the Managing the application section in the GitGuardian docs.
- Updating/Upgrading. Add steps that describe how to upgrade your app, KOTS, and/or embedded clusters. The Updating section in the Replicated KOTS documentation includes step-by-step procedures that you can copy to help you get started.
- Troubleshooting. Include information on how to generate support bundles, as well as any additional troubleshooting information for your app. (I’ll share a template you can use to write troubleshooting content below.)
For more detailed suggestions for organizing your docs, you can also watch my RepliCon talk called Creating installation docs for your users.
Writing Installation Docs for Apps Distributed with Replicated
You’ll likely spend the most time writing and testing your app installation docs, particularly if you offer several different installation options for your users. Luckily, for vendors that distribute one or more apps with Replicated, you can borrow content directly from the Replicated docs website rather than having to start completely from scratch.
For example, here’s the section in the Replicated docs site that includes information about installing with KOTS:
As shown above, your installation docs should include introductory content, prerequisites and requirements, and the actual installation procedures themselves:
- Installation overview
Include an overview that provides introductory information the user might need to understand before installing, such as the different installation options for your app (installing with KOTS in an existing cluster versus a VM or bare metal server, installing with Helm, air gap versus online installations, proxy installations, and so on).
An example of a good installation overview is DataStax’s Plan a Mission Control installation topic, which shows possible deployment topologies and describes the different installation options that users can choose between.
- Installation prerequisites and requirements
In addition to configuring preflight checks for your app, your docs should also clearly list all the prerequisites and requirements that your users need to address before they can install.
For apps installed with KOTS, you can copy or link to the installation requirements in the Replicated docs:
- For KOTS and kURL installation requirements, see Installation Requirements.
- For Embedded Cluster requirements, see Requirements in Using Embedded Cluster.
(Just be sure to add any app-specific requirements that are not covered in the Replicated docs. Wallaroo’s Prerequisites Guide provides a good example of this.)
- Installation procedures
For vendors that distribute one or more apps with Replicated, you might support a variety of different installation options, such as:
- Helm CLI installations
- KOTS installations in existing clusters
- KOTS installations in embedded clusters on a VM or bare metal server (with kURL or Embedded Cluster)
- Installations in air gap environments with no outbound internet access
You might also support installation options such as installing behind a proxy, the use of local private registries, or advanced RBAC options.
Replicated recommends that you add a separate topic or subsection in your docs site for each installation method, writing and thoroughly testing one method at a time.
Additionally, as part of your installation procedures, it’s also important to explain any configuration options for your app (such as the fields on the KOTS Admin Console config screen or the Helm values that you expose to your users). For example, KNIME’s Advanced settings section in their installation guide describes all the advanced configuration options, providing users with the information and recommendations they need in order to configure the app.
Writing Troubleshooting Content
Users often turn to the docs when things go wrong, and being able to find troubleshooting information that helps them self-resolve the issue is a big trust-builder. Troubleshooting content can also help reduce the burden on your support team by reducing the number of support requests that users have to make.
To make your troubleshooting information easy to read and search, use a standard, consistent format. In the Replicated docs site, we use a “Symptom, Cause, Solution” template, as shown in this example from our Snapshots troubleshooting page:
The “Symptom, Cause, Solution” template makes it really easy for users to understand why they are seeing a given error, and how to resolve it. It also makes it much easier for docs contributors to add new troubleshooting content without having to think about how they are going to format the information.
When writing this type of troubleshooting content, be sure to also include the exact error message that users might be seeing. This way, a "Control+F" or "Command+F" on the page for the error message will help users quickly find the info they are looking for.
Finally, for apps distributed with Replicated, you should also include a topic that explains how to collect a support bundle. To do this, you can copy existing content from the Replicated docs website:
- The Generating Support Bundles page describes how to generate support bundles from the CLI.
- Also, KOTS users can generate support bundles from the KOTS Admin Console.
Examples
For inspiration, take a look at these docs websites from other vendors that distribute their apps with Replicated: