[docs] create a new contributors' guide

docs/content/latest/contribute/_index.md

@@ -35,23 +35,23 @@ This is the C++ code and the unit tests that comprise the core of YugabyteDB. Yo
 
 ### Docs
 
-[YugabyteDB documentation](/) uses the Hugo framework. There are two types of docs issues - infrastructure enhancements and adding content. You can [follow the steps outlined here](https://github.com/yugabyte/yugabyte-db/tree/master/docs) to run a local version of the docs site. Next, look at the [contributing guide](https://github.com/yugabyte/yugabyte-db/blob/master/docs/CONTRIBUTING.md) to make your changes and contribute them.
+[YugabyteDB documentation](/) uses the Hugo framework. There are two types of docs issues - infrastructure enhancements, and adding or modifying content. You can [follow the steps outlined here](docs/) to get set up and make a contribution.
 
 ## Find an issue
 
-Issues are tagged with other useful labels as described below.
+Issues are tagged with labels, as described in the following table.
 
-| Key labels           |  Comments      |
-| -------------------- | -------------- |
-| `kind/bug`           | Bugs can have a small or large scope, so make sure to understand the bug. |
-| `area/documentation` | An issue related to the docs infrastructure, or content that needs to be added to the docs. |
-| `kind/enhancement`   | An enhancement is often done to an existing feature, and is usually limited in scope. |
-| `good first issue`   | A great first issue to work on as your initial contribution to YugabyteDB. |
-| `help wanted`        | Issues that are very useful and relatively standalone, but not actively being worked on. |
-| `kind/new-feature`   | An new feature does not exist. New features can be complex additions to the existing system, or standalone pieces. |
-| `kind/question`      | A question that needs to be answered. |
+| Key labels | Comments |
+| :--------- | :------- |
+| [kind/bug](https://github.com/yugabyte/yugabyte-db/issues?q=is%3Aopen+is%3Aissue+label%3A%22kind%2Fbug%22+) | Bugs can have a small or large scope, so make sure to understand the bug. |
+| [area/documentation](https://github.com/yugabyte/yugabyte-db/issues?q=is%3Aopen+is%3Aissue+label%3Aarea%2Fdocumentation+) | An issue related to the docs infrastructure, or content that needs to be added to the docs. |
+| [kind/enhancement](https://github.com/yugabyte/yugabyte-db/issues?q=is%3Aopen+is%3Aissue+label%3Akind%2Fenhancement) | An enhancement is often done to an existing feature, and is usually limited in scope. |
+| [good first issue](https://github.com/yugabyte/yugabyte-db/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) | A great first issue to work on as your initial contribution to YugabyteDB. |
+| [help wanted](https://github.com/yugabyte/yugabyte-db/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) | Issues that are very useful and relatively standalone, but not actively being worked on. |
+| [kind/new-feature](https://github.com/yugabyte/yugabyte-db/issues?q=is%3Aopen+is%3Aissue+label%3Akind%2Fnew-feature) | An new feature does not exist. New features can be complex additions to the existing system, or standalone pieces. |
+| [kind/question](https://github.com/yugabyte/yugabyte-db/issues?q=is%3Aopen+is%3Aissue+label%3Akind%2Fquestion) | A question that needs to be answered. |
 
-* If you are just starting out contributing to YugabyteDB, first off welcome and thanks! Look for issues labelled [good first issue](https://github.com/yugabyte/yugabyte-db/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22).
+* If you're just starting out contributing to YugabyteDB, first off welcome and thanks! Look for issues labelled [good first issue](https://github.com/yugabyte/yugabyte-db/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22).
 
 * If you have already contributed and are familiar, then look for issues with the [help wanted](https://github.com/yugabyte/yugabyte-db/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) label.
 

docs/content/latest/contribute/docs/_index.md

@@ -0,0 +1,65 @@
+---
+title: Contribute to the documentation
+headerTitle: Contribute to the documentation
+linkTitle: Documentation
+description: Contribute to the documentation
+image: /images/section_icons/index/quick_start.png
+headcontent: How to contribute to the YugabyteDB documentation
+type: page
+section: CONTRIBUTOR GUIDES
+menu:
+  latest:
+    identifier: docs
+    parent: contribute
+    weight: 2910
+---
+
+<div class="row">
+  <div class="col-12 col-md-6 col-lg-12 col-xl-6">
+    <a class="section-link icon-offset" href="docs-checklist/">
+      <div class="head">
+        <img class="icon" src="/images/section_icons/deploy/checklist.png" aria-hidden="true" />
+        <div class="title">Checklist</div>
+      </div>
+      <div class="body">
+        Explore the contribution process, from start to finish
+      </div>
+    </a>
+  </div>
+
+  <div class="col-12 col-md-6 col-lg-12 col-xl-6">
+    <a class="section-link icon-offset" href="docs-build/">
+      <div class="head">
+        <img class="icon" src="/images/section_icons/index/troubleshoot.png" aria-hidden="true" />
+        <div class="title">Build the docs</div>
+      </div>
+      <div class="body">
+        Run the docs site on your local machine
+      </div>
+    </a>
+  </div>
+
+  <div class="col-12 col-md-6 col-lg-12 col-xl-6">
+    <a class="section-link icon-offset" href="docs-edit/">
+      <div class="head">
+        <img class="icon" src="/images/section_icons/index/troubleshoot.png" aria-hidden="true" />
+        <div class="title">Edit the docs</div>
+      </div>
+      <div class="body">
+        Fork the repository and edit the docs
+      </div>
+    </a>
+  </div>
+
+  <div class="col-12 col-md-6 col-lg-12 col-xl-6">
+    <a class="section-link icon-offset" href="docs-style/">
+      <div class="head">
+        <img class="icon" src="/images/section_icons/architecture/concepts.png" aria-hidden="true" />
+        <div class="title">Style guide</div>
+      </div>
+      <div class="body">
+        Read the YugabyteDB documentation style guide
+      </div>
+    </a>
+  </div>
+</div>

docs/content/latest/contribute/docs/docs-build.md

@@ -0,0 +1,119 @@
+---
+title: Build the YugabyteDB docs locally
+headerTitle: Build the docs
+linkTitle: Build the docs
+description: Build the YugabyteDB docs locally
+image: /images/section_icons/index/quick_start.png
+type: page
+menu:
+  latest:
+    identifier: docs-build
+    parent: docs
+    weight: 2913
+isTocNested: true
+showAsideToc: true
+---
+
+## Prerequisites
+
+To run the docs site locally and edit the docs, you'll need:
+
+* **A text editor**, such as [Visual Studio Code](https://code.visualstudio.com)
+
+* **Command-line tools for Xcode** on macOS.
+
+    ```sh
+    $ xcode-select --install
+    ```
+
+    \
+    Xcode is many gigabytes. Install the command-line tools unless you actually need the full Xcode.
+
+* [**Homebrew**](https://brew.sh) on macOS or Linux.
+
+* **Node.js** v16.x, installable in several ways:
+
+  * From the [node.js website](https://nodejs.org/en/download/)
+  * Using Homebrew: `brew install node@16`
+  * Using NVM: `nvm use 16`
+
+* **Hugo**: `brew install hugo` gets you the latest version.
+
+* **A GitHub account**
+
+* **Git client**: The system Git binary is out of date, but works. If you like, you can use Homebrew to get a newer version (`brew install git`).
+
+## Fork the repository
+
+1. To make the commands in this section work correctly when you paste them, set an environment variable to store your GitHub username.
+
+    ```sh
+    export GITHUB_ID=your-github-id
+    ```
+
+1. Fork the `yugabyte-db` GitHub repository and create a local clone of your fork with a command like this:
+
+    ```sh
+    git clone https://github.com/$GITHUB_ID/yugabyte-db.git
+    ```
+
+1. Identify your fork as _origin_ and the original YB repository as _upstream_:
+
+    ```sh
+    cd yugabyte-db/
+    git remote set-url origin https://github.com/$GITHUB_ID/yugabyte-db.git
+    git remote add upstream https://github.com/yugabyte/yugabyte-db.git
+    ```
+
+1. Make sure that your local repository is still current with the upstream Yugabyte repository:
+
+    ```sh
+    git checkout master
+    git pull upstream master
+    git push origin
+    ```
+
+## Build the docs site {#live-reload}
+
+The YugabyteDB documentation is written in Markdown, and processed by Hugo (a static site generator) into an HTML site.
+
+To get the docs site running in a live-reload server on your local machine, run the following commands:
+
+```sh
+cd yugabyte-db/docs  # Make sure this is YOUR fork.
+npm ci               # Only necessary the first time you clone the repo.
+npm start            # Builds the docs and launches the live-reload server.
+```
+
+The live-reload server runs at <http://localhost:1313/> unless port 1313 is already in use. Check the output from the `npm start` command to verify the port in use.
+
+When you're done, type Ctrl-C stop the server.
+
+{{< note title="Not looking quite right?" >}}
+There's a transient bug in the live-reload build. If your local docs site doesn't look right, type Ctrl-C and re-run the `npm start` command.
+{{< /note >}}
+
+### Optional: Run a full build {#full-build}
+
+The live-reload server is the quickest way to get the docs running locally. If you want to run the build exactly the same way the CI pipeline does for a deployment, do the following:
+
+```sh
+cd yugabyte-db/docs
+npm run build
+```
+
+When the build is done, the `yugabyte-db/docs/public` folder contains a full HTML site, exactly the same as what's deployed on the live website at <https://docs.yugabyte.com/>.
+
+## Troubleshooting
+
+* Make sure the GUI installer for the command-line tools finishes with a dialog box telling you the install succeeded. If not, run it again.
+
+* If you get an error about missing command-line tools, make sure xcode-select is pointing to the right directory, and that the directory contains a `usr/bin` subdirectory. Run `xcode-select -p` to find the path to the tools. Re-run xcode-select --install.
+
+* If the live-reload site looks odd, stop the server with Ctrl-C and re-run `npm start`.
+
+## Next steps
+
+Need to edit an existing page? [Start editing](../docs-edit/) it now. (Optional: [set up your editor](../docs-editor-setup/).)
+
+Adding a new page? Use the [overview of sections](../docs-layout/) to find the appropriate location.

docs/content/latest/contribute/docs/docs-checklist.md

@@ -0,0 +1,51 @@
+---
+title: Docs contribution checklist
+headerTitle: Docs checklist
+linkTitle: Docs checklist
+description: Review the steps to start contributing documentation
+image: /images/section_icons/index/quick_start.png
+type: page
+menu:
+  latest:
+    identifier: docs-checklist
+    parent: docs
+    weight: 2911
+isTocNested: true
+showAsideToc: true
+---
+
+## Quick notes
+
+* [File issues in GitHub](#file-tickets).
+  * Internal users: please file Platform and Cloud issues in Jira.
+* Docs are written in Markdown and built using the Hugo static site generator.
+* For live previews as you work, install the command-line tools (macOS), Node.js, and Hugo. (See [How to build the docs](../docs-build/).)
+* Pull requests
+  * Open PRs against a fork of the yugabyte-db/docs repository, project Documentation.
+  * Assign a member of the docs team as a reviewer.
+
+## File docs issues and make suggestions {#file-tickets}
+
+Regardless of the type of problem (such as errors, bad links, out-of-date content, or new features), if you don't intend to [edit the docs](#edit-the-docs) and make a pull request right away to fix the problem, please create an issue in GitHub or Jira (Yugabyte internal users only) to track the problem.
+
+Every YugabyteDB docs page has a Contribute button that lets you file an issue or make a suggestion, both of which help you to create a GitHub issue. You can also create an issue [directly from GitHub](https://github.com/yugabyte/yugabyte-db/issues/new/choose).
+
+The GitHub issue template starts your issue title with `[docs]` for faster scanning, and adds the `area/documentation` label. You can also add the section of the docs (for example, `[docs] [troubleshooting]`) for added context. If you're an internal users, please add your ticket directly to the Documentation project.
+
+**Internal users**, please add a member of the docs team as a reviewer, in addition to any other technical reviewers.
+
+## Run the docs site locally
+
+Follow the instructions in [Build the docs](../docs-build/) to fork the repository and get the docs site running on your local machine.
+
+## Find the right page or section
+
+Use the [overview of sections](../docs-layout/) to help you find the page you want to edit, or the correct section for a new page you want to add.
+
+## Edit the docs {#edit-the-docs}
+
+Follow the instructions in [Edit the docs](../docs-edit/) to make your changes (read the [docs style guide](../docs-style/), too!) and submit a pull request.
+
+## Submit a pull request {#make-a-pr}
+
+Congratulations on the change! You should now [submit a pull request](../docs-edit/#make-a-pr) for review and leave a message on the Slack channel. After it's reviewed and approved, your docs change will get merged in.

docs/content/latest/contribute/docs/docs-edit.md

@@ -0,0 +1,75 @@
+---
+title: Edit the YugabyteDB docs
+headerTitle: Edit the docs
+linkTitle: Edit the docs
+description: Get set up and edit the YugabyteDB docs locally
+image: /images/section_icons/index/quick_start.png
+type: page
+menu:
+  latest:
+    identifier: docs-edit
+    parent: docs
+    weight: 2914
+isTocNested: true
+showAsideToc: true
+---
+
+After you've gotten the docs site [running locally](../docs-build/), make your changes. If you're going to be doing this a lot, read some [tips on setting up your text editor](../docs-editor-setup/).
+
+If you need to edit syntax diagrams, see [Edit syntax diagrams](../syntax-diagrams/).
+
+## Edit an existing page
+
+1. In your local copy of your yugabyte-db fork, make a branch.
+
+    ```sh
+    git checkout -b my-branch-name
+    ```
+
+1. Find your file in `docs/content/<version>/` and edit it as required.
+
+1. Verify that your changes look good in the live-reload server.
+
+    ```sh
+    npm start
+    ```
+
+1. Commit your changes.
+
+  ```sh
+  git commit -A -m "Your commit message here"
+  ```
+
+1. Push your changes to your fork.
+
+    ```sh
+    git push origin
+    ```
+
+At this point, you're ready to [create a pull request](#make-a-pr).
+
+## Add a new page
+
+Adding a new page is similar in most ways to editing an existing page, with the added complexity of sorting out the _frontmatter_ so that the page works correctly in the site, including showing up in the left-side navigation menu. See [how docs pages are structured](../docs-page-structure/) for more information.
+
+_More content in this section is coming soon._
+
+## Make a pull request {#make-a-pr}
+
+Once you've made your changes, make a pull request by telling GitHub to compare a branch _on your fork_ to the master branch on the main repository.
+
+### Use the PR preview build
+
+Preview builds take 10-15 minutes to build.
+
+All PR previews on the main repository are of the form `https://deploy-preview-ABCD--infallible-bardeen-164bc9.netlify.app/` where ABCD is the pull request number.
+
+Add a line in your PR's description to tag the Netlify bot and tell it where to launch the preview:
+
+`@netlify /latest/quick-start/`
+
+### Ask for a review
+
+**Internal contributors**, please tag a member of the docs team for review, along with technical reviewers as required, and let us know about your PR in the #docs channel in Slack.
+
+**External contributors**, please add the `area/documentation` label to your pull request, and let us know about it [in Slack](https://www.yugabyte.com/slack/).