Skip to content

Latest commit

 

History

History
182 lines (108 loc) · 10.1 KB

README.md

File metadata and controls

182 lines (108 loc) · 10.1 KB
Raw

Replicated Product Documentation

Table of Contents:

How to Contribute to the Documentation

Welcome to the repository for the Replicated documentation site.

This repository has been made public so that vendors and the open-source community can contribute to the content using the following methods:

  • 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.

  • 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 Zendesk ticket, Slack message, or by emailing [email protected].

Setting Up Local WYSIWYG Previews

This website is built using Docusaurus 2, a modern static website generator.

When you submit a PR in GitHub, Netlify builds a preview automatically. However, you can preview your changes locally. To do this, you must install yarn and run a build to create a Docusaurus preview in your local browser.

Install yarn

Run this command to install the yarn CLI:

$ yarn

Create a Local Development Server and WYSIWYG Preview

Run the following command to start a local development server and open up a browser window. Most changes are reflected live without having to restart the server. This preview shows the formatting and styles as they would render on the live site (also known as what-you-see-is-what-you-get or WYSIWYG), which can be more helpful than viewing content in a VS Code preview.

$ yarn start

If yarn start refuses to start, try reinstalling the yarn CLI. You do not need to uninstall yarn before reinstalling it. However, if you get build errors from your content, such as broken links, the Preview itself fails and error messages appear in the terminal that can help you troubleshoot the problems in the content.

Build

This command generates static content into the build directory and can be served using any static contents hosting service.

$ yarn build

Deployment

If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the gh-pages branch.

$ GIT_USER=<Your GitHub username> USE_SSH=true yarn deploy

Folder Structure and TOC

The folder structure is broken into several high-level categories under the main docs folder: vendor, enterprise, reference, release notes.

Images are under the static > images folder.

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.

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.

The right-hand TOC is created automatically when you add headings to a topic.

Topic Templates

Please copy the topic templates that are located in the templates folder to create new content. Right now we have a two templates for creating procedures:

  • A single procedure/task: procedure.md

  • A process/workflow or tutorial that contains multiple procedures/tasks: process-multiple-procedures.md

Save the new topic to the correct folder and be sure to follow the filenaming convention.

Filenaming

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.

Because we author content using Markdown, you must add the .md the file extension to the file name.

If you are adding a new topic to an existing feature category, follow the existing naming convention for that category.

Example: Concept topic

snapshots-backup-hooks.md

Example: Task topic

releases-creating-customer.md

Example: Tutorial

tutorial-ha-cluster-deploying.md

Images

  • Screenshots are use sparingly to minimize the maintenance of out-of-date content. However, we do include some screenshots to provide context.

  • 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.

  • We only use PNG format, which renders a better quality and lossless compression.

  • 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.

  • 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.

  • 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.

Using Markdown with our Docusaurus CSS

Replicated uses its own CSS, and Docusaurus supports its own specific Markdown syntax. The following table provides an overview of the supported syntax elements.

Element Syntax
Headings # H1, ## H2, ### H3
Bold **bold text**
Italic _italicized text_
Ordered List 1. First item (use 1. for each item)
Unordered List - or * (for each item)
Code or command in a sentence code
Link - external site [Title](https://www.example.com)
Link - topic in same folder [Title](filename) without file extension
Link - topic in different folder [Title](../folder/file-name) without file extension
Link - section in topic in same folder [Title](file-name#section-name)
Link - section in topic in different folder [Title](../folder/file-name#section-name)
Image ![alt text](images/<image-name>.png)

Note: Alt text, used with image syntax, is parsed by screen readers to support accessibility.

Admonitions

Note admonitions are formatted as follows:

:::note
text
:::

Important admonitions, typically used as a warning, are formatted as follows:

:::important
text
:::

Tables

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.

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.

Style Guidelines

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.

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.

Replicated employees can review more information in the Documentation Style Guide in the employee handbook.

SME and Editorial Reviews

All PRs that are submitted are reviewed by the Replicated Docs team for editorial review.

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.