diff --git a/docs/config.json b/docs/config.json index d2a87e35352ae..8619de00c47f6 100644 --- a/docs/config.json +++ b/docs/config.json @@ -1377,6 +1377,10 @@ "title": "How to Contribute", "slug": "/contributing/documentation/how-to-contribute/" }, + { + "title": "Reviewing Documentation Changes", + "slug": "/contributing/documentation/reviewing-docs/" + }, { "title": "Creating Documentation Issues", "slug": "/contributing/documentation/issues/" diff --git a/docs/pages/contributing/documentation.mdx b/docs/pages/contributing/documentation.mdx index afe34db17df29..72057ce405ded 100644 --- a/docs/pages/contributing/documentation.mdx +++ b/docs/pages/contributing/documentation.mdx @@ -24,11 +24,16 @@ the kind of documentation we want to transform our current documentation into. -- [How to Contribute to Teleport's Documentation](./documentation/how-to-contribute.mdx): -Follow this guide to start contributing changes to Teleport's documentation. -- [Documentation UI Reference](./documentation/reference.mdx): Consult -this resource to ensure that you are making the most of our documentation's user -interface components. -- [Style Guide](./documentation/style-guide.mdx): Use this reference to ensure our -docs are consistent and effective. -- [Creating documentation issues](./documentation/issues.mdx): Guidelines for creating Teleport documentation issues on GitHub +- [How to Contribute to Teleport's + Documentation](./documentation/how-to-contribute.mdx): Follow this guide to + start contributing changes to Teleport's documentation. +- [How to Review Documentation Changes](./documentation/reviewing-docs.mdx): + Read our recommended approach to preview docs changes in order to review pull + requests. +- [Documentation UI Reference](./documentation/reference.mdx): Consult this + resource to ensure that you are making the most of our documentation's user + interface components. +- [Style Guide](./documentation/style-guide.mdx): Use this reference to ensure + our docs are consistent and effective. +- [Creating documentation issues](./documentation/issues.mdx): Guidelines for + creating Teleport documentation issues on GitHub diff --git a/docs/pages/contributing/documentation/reviewing-docs.mdx b/docs/pages/contributing/documentation/reviewing-docs.mdx new file mode 100644 index 0000000000000..820573b984235 --- /dev/null +++ b/docs/pages/contributing/documentation/reviewing-docs.mdx @@ -0,0 +1,92 @@ +--- +title: "How to Review Teleport Documentation Changes" +description: "In this guide, we will show you how to set up your environment so you can review pull requests that propose changes to the Teleport documentation." +--- + +Teleport uses GitHub pull requests to manage documentation changes. You can set +up your environment to preview docs changes on a local development server, then +leave a review on the pull request. + +## Step 1/2 Set up a docs site clone + +The Teleport documentation site is based on the GitHub repository +`gravitational/docs`, and includes documentation for all supported versions of +Teleport. To achieve this, the `gravitational/docs` repo includes git submodules +for different branches of the Teleport source repository, +`gravitational/teleport`, which also includes the documentation for a particular +version of Teleport: + +```mermaid +flowchart RL + subgraph docs["gravitational/docs"] + ver1["content/1.x"] + ver2["content/2.x"] + ver3["content/3.x"] + end + + subgraph teleport["gravitational/teleport"] + end + + teleport-- "branch/v1" --> ver1["content/1.x"] + teleport-- "branch/v2" --> ver2["content/2.x"] + teleport-- "branch/v3" --> ver3["content/3.x"] +``` + +Clone the `gravitational/docs` repository: + +```code +$ git clone https://github.com/gravitational/docs +``` + +Navigate to the root of your local clone of the `gravitational/docs` repository +and run the following command to populate the `content` directory: + +```code +$ yarn git-update +``` + +## Step 2/2 Visit preview pages on the development server + +Navigate to the directory under `content` that corresponds to the latest +released version of Teleport. + +```code +$ cd content/(=teleport.major_version=).x +``` + +Docs PRs fall within `gravitational/teleport`. Check out the branch associated +with the PR: + +```code +$ git switch +``` + +Navigate to the root of your `gravitational/docs` clone and run the following +command to start the development server: + +```code +$ yarn dev +``` + +The development server listens on port `3000` by default. (It increments the +port if you have other development server instances running.) + +On GitHub, see which docs pages the pull request has changed and navigate to +them within the development server. + +On the docs site, files within `docs/pages` of `gravitational/teleport` +correspond to pages within `localhost:3000/docs`. + +When assigning URL paths to docs pages, the docs site strips the `/pages/` +segment and the `.mdx` extension. For example, `docs/pages/get-started.mdx` +corresponds to `docs/get-started/`. `docs/pages/index.mdx` corresponds to the +root of `localhost:3000/docs`. + +## Next steps + +- While reviewing documentation changes, you will often run into partials, + admonitions, and other elements in the docs engine's library of UI components. + Read about these in the [UI Reference](./reference.mdx). +- To make sure that docs pages make consistent use of language and structure, + you should get familiar with the Teleport documentation [style + guide](./style-guide.mdx).