Updates contributing page

content/docs/community/contributing.md

@@ -8,8 +8,8 @@ description: This document describes how you can find issues to work on, fix/add
 
 First of all, thank you for considering contributing to Pomerium! You can have a direct impact on Pomerium by helping with its code or documentation.
 
-- To contribute to Pomerium, open a [pull request](https://github.com/pomerium/pomerium/pulls) (PR) to the Pomerium repository.
-- To contribute to the documentation, open a [pull request](https://github.com/pomerium/documentation/pulls) (PR) to the documentation repository.
+- To contribute to Pomerium, open a [pull request](https://github.com/pomerium/pomerium/pulls) (PR) to the Pomerium repository
+- To contribute to the documentation, open a PR to the documentation repository
 
 If you're new to our community, that's okay: **we gladly welcome pull requests from anyone, regardless of your native language or coding experience.**
 
@@ -35,12 +35,14 @@ Here are some of the expectations we have of contributors:
 
 - **Use comments properly.** We expect good godoc comments for package-level functions, types, and values. Comments are also useful whenever the purpose for a line of code is not obvious.
 
-- **Recommended reading**
+:::info **Recommended reading**
 
-  - [CodeReviewComments](https://github.com/golang/go/wiki/CodeReviewComments)
-  - [Linus Torvalds describes a good commit message](https://gist.github.com/matthewhudson/1475276)
-  - [Best Practices for Maintainers](https://opensource.guide/best-practices/)
-  - [Shrinking Code Review](https://alexgaynor.net/2015/dec/29/shrinking-code-review/)
+- [**CodeReviewComments**](https://github.com/golang/go/wiki/CodeReviewComments)
+- [**Linus Torvalds describes a good commit message**](https://gist.github.com/matthewhudson/1475276)
+- [**Best Practices for Maintainers**](https://opensource.guide/best-practices/)
+- [**Shrinking Code Review**](https://alexgaynor.net/2015/dec/29/shrinking-code-review/)
+
+:::
 
 ### Development
 
@@ -93,46 +95,62 @@ Pomerium uses the [zerolog](https://github.com/rs/zerolog) package for logging.
 
 ## Docs
 
-Pomerium's documentation is available at [https://www.pomerium.io/docs](https://www.pomerium.io/docs). If you find a typo, feel a section could be better described, or have an idea for a totally new application or section, don't hesitate to make a pull request change. There are few ways you can do this.
+Pomerium's documentation is available at [https://www.pomerium.io/docs](https://www.pomerium.io/docs). If you find a typo, feel a section could be better described, or have an idea for a totally new application or section, don't hesitate to make a PR change. There are few ways you can do this.
 
 ### Simple edits
 
-The easiest way to fix minor documentation issues in Pomerium is to click on "Edit this page in Github" on any page.
+The easiest way to fix minor documentation issues in Pomerium is to click on the **Edit this page** link at the bottom of any page.
+
+![Selecting the Edit this page link on a docs page](./img/contributing-edit-this-page.png)
 
-![edit this page link](./img/contributing-edit-this-page.png)
+Doing so will redirect you to the the respective file in the Documentation repository. Here, you can [update the page](https://guides.github.com/features/mastering-markdown/) and commit your changes.
 
-Doing so will create a [fork](https://help.github.com/en/articles/fork-a-repo) of the project, allow you to [update the page](https://guides.github.com/features/mastering-markdown/), and create a [pull request](https://help.github.com/en/articles/about-pull-requests).
+Committing your changes will create a new branch and start a PR.
 
-![edit this page link using github](./img/contributing-edit-this-page-github.png)
+![Adding proposed changes in the docs repository](./img/contributing-proposed-changes.png)
 
 ### Bigger changes
 
 If you need to add a new page, or would like greater control over the editing process you can edit the docs similar to how you would make changes to the source code.
 
-#### Pre-requisites
+#### Prerequisites
+
+We use [Docusaurus](https://docusaurus.io/) to generate our docs. Docusaurus is a React-powered static-site generator designed for documentation.
 
-We use [VuePress](https://vuepress.vuejs.org) to generate our docs. Vuepress is a simple, [markdown](https://v1.vuepress.vuejs.org/config/#markdown) and [Vue.js](https://v1.vuepress.vuejs.org/config/#markdown) based static site generator. Before building the docs, you'll need to install the following pre-requisites.
+Before building the docs, you'll need the following packages:
 
-1. [Node.js](https://nodejs.org/en/download/).
-2. [Yarn](https://yarnpkg.com/lang/en/docs).
+- [Node.js](https://nodejs.org/en/download/)
+- [Yarn](https://yarnpkg.com/lang/en/docs)
 
 #### Make changes
 
-Once you have Nodejs and Yarn installed, simply run `make docs` in a terminal which will install any required node packages as well as start up a development server. You should see something like the below, with a link to the local doc server.
+Once you've installed Node and Yarn, in a terminal run the following command:
 
 ```bash
-success [19:02:54] Build f9f5f7 finished in 246 ms! ( http://localhost:8081/ )
+yarn start
+```
+
+You should see a link to the development server:
+
+```bash
+[INFO] Starting the development server...
+[SUCCESS] Docusaurus website is running at: http://localhost:3001/
 ```
 
 Once you have the development server up and running, any changes you make will automatically be reloaded and accessible in your browser.
 
 To add a new document, simply add a new file with the `.md` markdown extension. For example, this document would be `docs/community/contributing.md`.
 
-To add a new document to the side or top-bar navigation, see `docs/.vuepress/config.js` and add that document to the desired section.
+To make changes to the sidebar or navigation, see the following Docusaurus docs for instructions:
+
+- [Sidebar](https://docusaurus.io/docs/sidebar)
+- [Navbar](https://docusaurus.io/docs/api/themes/configuration#navbar)
+
+### PR previews
 
-### PR Previews
+We use [Netlify](https://www.netlify.com) to build and host our docs. A nice feature of Netlify is the [Deploy Preview URL](https://docs.netlify.com/site-deploys/deploy-previews/#deploy-preview-urls), which generates a link for PRs. This is helpful if you want to compare your local changes to what will ultimately be deployed in production.
 
-We use [Netlify](https://www.netlify.com) to build and host our docs. One of nice features of Netlify, is that a preview of the docs are automatically created for each new pull request that is made, which lets you be sure that the version of your docs that you see locally match what will ultimately be deployed in production.
+After you've pushed your PR, a member of the documentation team will review your PR and communicate any next steps or suggestions before the PR is merged.
 
 [configuration variables]: /docs/reference
 [docker compose]: https://docs.docker.com/compose/