[docs] update contributors guide

docs/.markdownlint.json

@@ -1,13 +1,27 @@
 {
   "default": true,
-  "MD007": {"indent": 2},
-  "MD009": {"list_item_empty_lines": false, "strict": true},
-  "MD013": false,
-  "MD014": false,
-  "MD024": {"siblings_only": true},
-  "MD033": false,
-  "MD036": false,
-  "MD041": {"front_matter_title": "^\\s*title\\s*[:=]"},
-  "MD046": {"style": "fenced"},
-  "MD048": {"style": "backtick"}
-}
+  "code-block-style": {
+    "style": "fenced"
+  },
+  "code-fence-style": {
+    "style": "backtick"
+  },
+  "commands-show-output": false,
+  "line-length": false,
+  "no-duplicate-heading": {
+    "siblings_only": true
+  },
+  "first-line-heading": {
+    "front_matter_title": "^\\s*title\\s*[:=]"
+  },
+  "link-fragments": false,
+  "no-emphasis-as-heading": false,
+  "no-inline-html": false,
+  "no-trailing-spaces": {
+    "list_item_empty_lines": false,
+    "strict": true
+  },
+  "ul-indent": {
+    "indent": 2
+  }
+}

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

@@ -28,15 +28,14 @@ To run the docs site locally and edit the docs, you'll need:
 
 * [**Homebrew**](https://brew.sh) on macOS or Linux.
 
-* **Node.js**, installable in several ways:
+* **[Node.js](https://nodejs.org/en/download/)** LTS (16) or current (18):
 
-  * Using Homebrew: `brew install node`
-  * Using NVM: `nvm use node`
-  * From the [node.js website](https://nodejs.org/en/download/)
+  * Using Homebrew: `brew install node` for current, or `brew install node@16` for LTS
+  * Using NVM: `nvm install 18` for current, or `nvm install --lts` for LTS
 
-* **Hugo**: `brew install hugo` gets you the latest version.
+* **Hugo**: `brew install hugo` installs the latest version.
 
-* **Go**: `brew install go` gets you the latest version.
+* **Go**: `brew install go` installs the latest version.
 
 * **A GitHub account**.
 
@@ -56,13 +55,15 @@ Create the folder with `mkdir ~/.hugo-cache`, then start a new terminal session.
 
 ## 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.
+1. To make the commands in this section work correctly when you paste them, set an environment variable to store your GitHub username. (Replace `your-github-id` here with your own GitHub ID.)
 
     ```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:
+1. Fork the [`yugabyte-db` GitHub repository](https://github.com/yugabyte/yugabyte-db/).
+
+1. Create a local clone of your fork:
 
     ```sh
     git clone https://github.com/$GITHUB_ID/yugabyte-db.git

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

@@ -18,13 +18,21 @@ If you need to edit syntax diagrams, see [Edit syntax diagrams](../syntax-diagra
 
 ## Edit an existing page
 
-1. In your local copy of your yugabyte-db fork, make a branch.
+1. In your local copy of your `yugabyte-db` fork, make sure your local `master` branch is up to date, and send any changes to GitHub's copy of your fork.
+
+    ```sh
+    git checkout master
+    git pull upstream master  # get up to date with the Yugabyte GitHub repo
+    git push origin           # send any changes to your fork on GitHub
+    ```
+
+1. Next, make a branch.
 
     ```sh
     git checkout -b my-branch-name
     ```
 
-1. Find your file in `docs/content/<version>/` and edit it as required.
+1. Find your file(s) in `docs/content/<version>/...` and edit as required.
 
 1. Verify that your changes look good in the live-reload server.
 
@@ -64,16 +72,16 @@ Preview builds take 5 minutes to build.
 
 All PR previews on the main repository are of the form `https://deploy-preview-ABCDE--infallible-bardeen-164bc9.netlify.app/` where ABCDE 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:
+Add a line in your pull request's description to tag the Netlify bot and tell it where to launch the preview:
 
 `@netlify /preview/quick-start/`
 
 ### Run a link checker
 
-https://linkchecker.github.io/linkchecker/
+<https://linkchecker.github.io/linkchecker/>
 
 ### 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.
+**Internal contributors**, please add the `area/documentation` label to your pull request, 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/).

docs/content/preview/contribute/docs/docs-editor-setup.md

@@ -24,9 +24,9 @@ To install an extension in Visual Studio Code, click the Extensions icon in the
 
 * **GitHub Pull Requests and Issues**, by GitHub: Pretty good pull request support. Not perfect, and can get confused with large PRs, but handy on a regular basis.
 
-* **GitLens — Git supercharged**, by Eric Amodio: Useful git tooling, including per-line blame/history.
+* **GitLens — Git supercharged**, by Eric Amodio: Useful Git tooling, including per-line blame/history.
 
-* **Markdown Preview Enhanced**, by Yiyi Wang: Even nicer markdown previews.
+* **Markdown Preview Enhanced**, by Yiyi Wang: Even nicer Markdown previews.
 
 * **markdownlint**, by David Anson: Lints your markdown formatting to catch errors and inconsistencies.