Deprecation notice: This repo has been deprecated and is no longer maintained. For up-to-date guidance on writing documentation for applications distributed with Replicated, including examples and templates, see Writing Great Documentation for On-Prem Software Distributed with Replicated.
This repository contains documentation templates for software vendors distributing their application with Replicated. Vendors can use these templates to write documentation for their end users that describes how to install and manage their application.
To use the templates:
- Copy the contents of the templates from the
/templatesdirectory of this repository and add them to your own documentation git repository. - Open the templates in a text editor, and use the instructions and guidance in the templates to add your app-specific documentation.
- Remove any sections from the templates that do not apply to your uses cases.
For more information, see About the Templates below.
This section provides introductory information about the templates, including common use cases for each and additional guidance.
The installation documentation that you provide to your end users should include a topic that lists any installation requirements and prerequisites:
- Prerequisites: Tasks a user must complete before they begin installation.
- Requirments: Required specifications that your end users environment must meet in order to install.
Including a topic at the start of your installation docs that lists the requirements and prerequisites helps to avoid your customers running into errors or issues in the middle of installation process, which can cause frustration and confusion.
There are several requirements that apply to all applications distributed with Replicated, which are linked from the template. Add any additional requirements and prerequisites that are specific to your application. The template includes some examples to help you get started.
See Installation Requirements and Prerequisites Template.
As part of the installation process, your users provide their configuration preferences for your application on the Configuration screen in the admin console. After they configure the application, they can then run preflight checks and deploy.
The configuration options provided to your users are specific to your application. You define the configuration options when packaging your application with Replicated. For more information, see About the Configuration Screen in the Replicated documentation.
It is important to provide a topic in your documentation that includes a step-by-step procedure describing each field on the Configuration screen. This might include:
- Listing information that users need to gather before they can complete the fields on the Configuration screen.
- Describing the common use cases for why a user might choose one configuration option over another.
- Providing any recommendations that you have.
- Clarifying requirements for any of the fields.
The template for this topic includes an outline of how to write this step-by-step procedure. It also includes a pre-written section on how to run preflight checks and deploy the application after configuring the application.
See Configuring and Deploying the Application Template.
The troubleshooting template provides an outline for writing a topic that helps your users to troubleshoot common errors. To make the troubleshooting topic easy to read and search, we recommend using a standard format of: Symptom, Cause, Solution.
One common use case for including a troubleshooting topic in your documentation is to provide additional guidance to users in how to correct and warnings or failures in your preflight checks.
For additional guidance and documentation examples, see Help creating Replicated Documentation For end user Kubernetes installs? on the Replicated Community site.