The preview docs site hosts docs for upcoming features that we share with customers. Unlike the public docs site, the preview docs site isn't publicly editable and doesn't appear in search engine results. Users can't navigate from one preview doc to another, because the site isn't indexed.
Because the preview docs site is located in a different repository than the public docs site, contributing looks a little different. By the end of this doc, you'll be ready to create a new doc for the preview site.
Set up your local environment
If you've previously cloned the beta-docs-site repo on your computer, skip to step 3.
- Go to the
beta-docs-site repo. If you do not have access, contact the #doc-eng-help Slack channel for help.
- Clone the beta-docs-site repo on your computer.
- Make sure you're working in the correct repo on Github Desktop.
- Create a branch off the
Create a new preview doc
Despite differences between the public and preview docs sites, the formatting and syntax of their content is largely the same. Once you're in your working branch:
- Using your text editor, create a new
.mdxfile or copy an existing preview doc for the frontmatter template.
- Save the file in
- Write your content, making sure to include any info about signing up for and requesting access to the preview feature you're documenting.
- Commit your changes and create a pull request.
- Share the preview link with reviewers and implement any feedback.
- Merge the final PR.
- Create the official link by pasting the file path name after
- Provide reviewers the official link to share with customers.
Optional boilerplate text
When writing a doc for preview, you may want to include a callout with boilerplate text at the top of the doc. This text can be used to orient your reader, providing them with important information about the feature's availability and relevant contact information.
For example, boilerplate text for a preview doc might read:
This feature was released on January 1, 202X and is in preview. To get access to it, reach out to your account manager.
You might want to exclude boilerplate text if the information is too lengthy, included elsewhere on the page, or irrelevant to the doc.
Additional guidance for internal contributors
As an internal contributor looking to edit a preview doc, you'll need access to the beta-docs-site repo. If you don't have access, ask the #doc-eng-help Slack channel to add you as a contributor. Once you have access, create your own branch off the
main branch and make your edits there.