|
1 | 1 | # [Replicated](https://www.replicated.com/) Product Documentation |
2 | 2 |
|
3 | | -## Table of Contents: |
4 | | - |
5 | | -* [For Vendors: How to Create Enterprise Documentation](#for-software-vendors-using-this-repository-to-create-your-documentation) |
6 | | -* [How to Contribute to the Documentation](#how-to-contribute-to-the-documentation) |
7 | | -* [Setting Up Local WYSIWYG Previews](#setting-up-local-wysiwyg-previews) |
8 | | -* [Folder Structure and TOC](#folder-structure-and-toc) |
9 | | -* [Topic Templates](#topic-templates) |
10 | | -* [Filenaming](#filenaming) |
11 | | -* [Images](#images) |
12 | | -* [Using Markdown with our Docusaurus CSS](#using-markdown-with-our-docusaurus-css) |
13 | | -* [Style Guidelines](#style-guidelines) |
14 | | -* [SME and Editorial Reviews](#sme-and-editorial-reviews) |
15 | | - |
16 | 3 | Welcome to the repository for the [Replicated documentation site](https://docs.replicated.com/). |
17 | 4 |
|
18 | | -## For Software Vendors: Using this Repository to Create Your Documentation |
| 5 | +## Contribute to the Replicated Docs |
19 | 6 |
|
20 | | -Software vendors using Replicated to distribute their application can copy the documentation in this repository to create docs for their own users. The following directories contain documentation for enterprise users about how to use the Replicated admin console and the kots CLI: |
| 7 | +This repository has been made public so that vendors and the open-source community can contribute to the content using the following methods: |
21 | 8 |
|
22 | | -* **docs/enterprise**: The `docs/enterprise` directory includes documentation for installing, updating, monitoring, and managing applications with the admin console and the kots CLI. See [`docs/enterprise`](https://github.com/replicatedhq/replicated-docs/tree/main/docs/enterprise). For the published version of the enterprise content, see [https://docs.replicated.com/enterprise](https://docs.replicated.com/enterprise/installing-overview). |
23 | | -* **docs/reference**: The `docs/reference` directory includes reference documentation for the kots CLI commands. This includes details on each of the kots CLI commands and associated flags. See [`docs/reference`](https://github.com/replicatedhq/replicated-docs/tree/main/docs/reference). For the published version of the kots CLI reference content, see [Installing the kots CLI](https://docs.replicated.com/reference/kots-cli-getting-started). |
| 9 | +- **Submit a PR** You can submit a PR directly from a specific topic in the documentation by clicking the **Create pull request or raise issue on GitHub** at the bottom of the page. This method lets you edit the content directly and commit your changes on a new branch. After submitting your proposed changes, the Replicated team will verify the accuracy of the changes and perform an editorial review. If the PR is approved, it will be merged directly into the main branch. |
24 | 10 |
|
25 | | -To create your own documentation, review the content in these directories and copy and paste the markdown files into your own repository. Edit the content as necessary to add information and terminology specific to your application, and remove content that does not apply for your use cases. |
| 11 | +- **Open a Github Issue** - To open a GitHub issue for this repository, click the Issues tab and click **New Issue**. This method may be more useful when you want to report a bug specifically for the documentation. If you are having an issue with the product itself, we encourage you to report it to us in a support issue submitted in the vendor portal. |
26 | 12 |
|
27 | | -After copying the generic content from the above directories in this repository, you can then add your own application-specific content. For example, there are likely prerequisites, configuration options, and troubleshooting steps that are unique to your application. |
| 13 | +## Folder Structure and Sidebar |
28 | 14 |
|
29 | | -For help getting started with writing documentation that is specific to your application, see the [vendor-docs-starter](https://github.com/replicatedhq/vendor-docs-starter) repository. The `vendor-docs-starter` repository contains templates, guidance, and examples that you can use to write the end user documentation for your application. |
| 15 | +The folder structure is broken into several high-level categories under the main `docs` folder: vendor, enterprise, reference, release notes. |
30 | 16 |
|
31 | | -## How to Contribute to the Documentation |
| 17 | +Images are under the `static` > `images` folder. |
32 | 18 |
|
33 | | -This repository has been made public so that vendors and the open-source community can contribute to the content using the following methods: |
| 19 | +The TOC is managed in the `sidebar.js` file. You only need to edit the `sidebar.js` file when you are adding a new topic or deleting an existing topic. The `sidebar.js` file is the one that causes most of the merge conflicts because many technical writers are working on content daily. You will need to accept the changes from other contributors if you are committing a PR. |
34 | 20 |
|
35 | | -- **Submit a PR** You can submit a PR directly from a specific topic in the documentation by clicking the **Create pull request or raise issue on GitHub** at the bottom of the page. This method lets you edit the content directly and commit your changes on a new branch. After submitting your proposed changes, the Replicated team will verify the accuracy of the changes and perform an editorial review. If the PR is approved, it will be merged directly into the main branch. |
| 21 | +Don't worry if you're not sure where in the TOC a new topic belongs. When you submit your PR, the Documentation team will edit it and help to find the right placement. |
36 | 22 |
|
37 | | -- **Open a Github Issue** - To open a GitHub issue for this repository, click the Issues tab and click **New Issue**. This method may be more useful when you want to report a bug specifically for the documentation. If you are having an issue with the product itself, we encourage you to report it to us in a support issue submitted in the vendor portal. |
| 23 | +The right-hand TOC is created automatically when you add headings to a topic. |
38 | 24 |
|
39 | 25 | ## Setting Up Local WYSIWYG Previews |
40 | 26 |
|
@@ -87,118 +73,9 @@ Before pushing changes to the remote repository, build and serve the site locall |
87 | 73 | npm run serve |
88 | 74 | ``` |
89 | 75 |
|
90 | | -## Folder Structure and TOC |
91 | | - |
92 | | -The folder structure is broken into several high-level categories under the main `docs` folder: vendor, enterprise, reference, release notes. |
93 | | - |
94 | | -Images are under the `static` > `images` folder. |
95 | | - |
96 | | -The TOC is managed in the `sidebar.js` file. You only need to edit the `sidebar.js` file when you are adding a new topic or deleting an existing topic. The `sidebar.js` file is the one that causes most of the merge conflicts because many technical writers are working on content daily. You will need to accept the changes from other contributors if you are committing a PR. |
97 | | - |
98 | | -Don't worry if you're not sure where in the TOC a new topic belongs. When you submit your PR, the Documentation team will edit it and help to find the right placement. |
99 | | - |
100 | | -The right-hand TOC is created automatically when you add headings to a topic. |
101 | | - |
102 | | -## Topic Templates |
103 | | - |
104 | | -You can find topic templates in the `docs/templates` folder. These templates are useful for anyone creating a new topic in this repository. |
105 | | - |
106 | | -If you are using the templates to create a new topic in this repository, save the new file to the correct folder (`docs/vendor`, `docs/enterprise`, `docs/reference`, etc) and be sure to follow the [filenaming convention](#filenaming). |
107 | | - |
108 | | -For additional templates designed for software vendors writing the end user documentation for their applications, see the [vendor-docs-starter](https://github.com/replicatedhq/vendor-docs-starter) repository. |
109 | | - |
110 | | -## Filenaming |
111 | | - |
112 | | -If you are adding a new file, it must be named following our naming conventions. The file name should always start with the feature type (such as licenses, helm, or gitops). Depending on the content type, it typically also includes a secondary descriptor and a verb. Verbs are used when you are creating a task topic. |
113 | | - |
114 | | -Because we author content using Markdown, you must add the `.md` the file extension to the file name. |
115 | | - |
116 | | -If you are adding a new topic to an existing feature category, follow the existing naming convention for that category. |
117 | | - |
118 | | -**Example: Concept topic** |
119 | | - |
120 | | -`snapshots-backup-hooks.md` |
121 | | - |
122 | | -**Example: Task topic** |
123 | | - |
124 | | -`releases-creating-customer.md` |
125 | | - |
126 | | -**Example: Tutorial** |
127 | | - |
128 | | -`tutorial-ha-cluster-deploying.md` |
129 | | - |
130 | | - |
131 | | -## Images |
132 | | - |
133 | | -* Screenshots are use sparingly to minimize the maintenance of out-of-date content. However, we do include some screenshots to provide context. |
134 | | - |
135 | | -* Use a focused area of the UI, unless the entire screen is truly needed. If using a focused area, use approximately 400 pixels for the width. If capturing the entire screen, use a maximum of 600 pixels for the width. |
136 | | - |
137 | | -* We only use PNG format, which renders a better quality and lossless compression. |
138 | | - |
139 | | -* For privacy and legal purposes, do not reveal personal information, IP addresses, domain information, login credentials and so on in screenshots, code blocks, or text. |
140 | | - |
141 | | -* Add _alt text_ for all images to provide accessibility. The user will hear the alt text spoken out loud by the screen reader, so it is important to use succinct text that is clear and complete. For more information about alt text formatting, see the following section. |
142 | | - |
143 | | -* For images that are difficult to see, add a link below the image where the reader can view a larger version: `[View a larger version of this image](PATH-TO-LARGER-IMAGE-FILE)` where `PATH-TO-LARGER-VERSION` is the path to the larger image in the `static/images` folder. For an example, see the private registry diagram in [Connecting to a Private Image Registry](https://docs.replicated.com/vendor/packaging-private-images#about-connecting-to-an-external-registry). |
144 | | - |
145 | | - |
146 | | -## Using Markdown with our Docusaurus CSS |
147 | | - |
148 | | -Replicated uses its own CSS, and Docusaurus supports its own specific Markdown syntax. The following table provides an overview of the supported syntax elements. |
149 | | - |
150 | | -| Element | Syntax | |
151 | | -|---------------------------------------------|-------------------------------------------------------| |
152 | | -| Headings | `# H1`, `## H2`, `### H3` | |
153 | | -| Bold | `**bold text**` | |
154 | | -| Italic | `_italicized text_` | |
155 | | -| Ordered List | `1.` First item (use `1.` for each item) | |
156 | | -| Unordered List | `-` or `*` (for each item) | |
157 | | -| Code or command in a sentence | ``code`` | |
158 | | -| Link - external site | `[Title](https://www.example.com)` | |
159 | | -| Link - topic in same folder | `[Title](filename) without file extension` | |
160 | | -| Link - topic in different folder | `[Title](../folder/file-name) without file extension` | |
161 | | -| Link - section in topic in same folder | `[Title](file-name#section-name)` | |
162 | | -| Link - section in topic in different folder | `[Title](../folder/file-name#section-name)` | |
163 | | -| Image | `` | |
164 | | - |
165 | | -**Note:** Alt text, used with image syntax, is parsed by screen readers to support accessibility. |
166 | | - |
167 | | -### Admonitions |
168 | | - |
169 | | -Note admonitions are formatted as follows: |
170 | | - |
171 | | -``` |
172 | | -:::note |
173 | | -text |
174 | | -::: |
175 | | -``` |
176 | | - |
177 | | -Important admonitions, typically used as a warning, are formatted as follows: |
178 | | - |
179 | | -``` |
180 | | -:::important |
181 | | -text |
182 | | -::: |
183 | | -``` |
184 | | - |
185 | | -### Tables |
186 | | - |
187 | | -Traditional markdown for tables can be limiting. Instead, we use HTML tables, which lets us manage the width of the table columns. The template topic `procedure.md` contains an example of the HTML formatting for tables. |
188 | | - |
189 | | -**Note:** There are still many instances of the old markdown table formatting in the content that was carried over from the content migration, but we do not encourage the use of it going forward. |
190 | | - |
191 | | -## Style Guidelines |
192 | | - |
193 | | -Whether you are editing existing content or adding a new topic, our goal is to make it task-based. The `procedure.md` template provides the formatting guidelines that you need. You can also see a published example of a task [here](https://docs.replicated.com/vendor/releases-creating-customer). |
194 | | - |
195 | | -Replicated product documentation has in-house style guidelines that the Documentation team uses when reviewing your PR. Please feel free to just add the content you need, knowing that our team will be there to assist with editorial reviews and information architecture, such as TOC placement, whether to create a task, and so on. The Documentation team will actively write content, not just give editorial reviews, so we take the heavy burden off of you. We encourage your contributions in the true open-source spirit. |
196 | | - |
197 | | -Replicated employees can review more information in the Documentation Style Guide in the employee handbook. |
198 | | - |
199 | | - |
200 | | -## SME and Editorial Reviews |
| 76 | +## Replicated Documentation for LLMs |
201 | 77 |
|
202 | | -All PRs that are submitted are reviewed by the Replicated Docs team for editorial review. |
| 78 | +Replicated supports the [llms.txt](https://llmstxt.org/) convention for making documentation available to LLMs. |
203 | 79 |
|
204 | | -Content that is submitted by our customers and the open-source community are also reviewed by our Replicated subject matter experts (SMEs) to help ensure technical accuracy. |
| 80 | +- [llms.txt](https://docs.replicated.com/llms.txt): This file contains Markdown versions of key docs pages. |
| 81 | +- [llms-full.txt](https://docs.replicated.com/llms-full.txt): This file contains the contents of the docs/ directory in the [replicated-docs](https://github.com/replicatedhq/replicated-docs) repository. |
0 commit comments