From 1de916112c00ca7669331ccaabf585375f4c6398 Mon Sep 17 00:00:00 2001
From: Jason Fairchild <jason@fairchild.au>
Date: Tue, 16 Jul 2024 00:53:55 +1000
Subject: [PATCH] docs(#91): WIP changes to CONTRIBUTING.md

---
 README.md            | 11 +++------
 docs/CONTRIBUTING.md | 57 ++++++++++++++++++++++++++++++++++++++------
 2 files changed, 53 insertions(+), 15 deletions(-)

diff --git a/README.md b/README.md
index f63f6b9f..2ff0cce8 100644
--- a/README.md
+++ b/README.md
@@ -79,14 +79,9 @@ directory as an argument! See below for installation options.
 - run `./configure <install_dir>`
 - run `make install`
 
-> [!NOTE]  
-> Some Linux distributions package a version of Node.js that will fail to build Vivify. In that case you'll need to download an official version from https://nodejs.org/. The recommended method is to use [Node Version Manager (nvm)](https://github.com/nvm-sh/nvm/blob/master/README.md)
->
-> ```
-> curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
-> exec bash
-> nvm install node
-> ```
+> [!TIP]  
+> If you are having trouble building Vivify, or you'd like more detailed build
+> instructions, see our [CONTRIBUTING](CONTRIBUTING.md) page
 
 ## Get help
 
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
index 343257a7..0f82a7b4 100644
--- a/docs/CONTRIBUTING.md
+++ b/docs/CONTRIBUTING.md
@@ -9,21 +9,60 @@ sure you follow the steps below:
 - Make sure you are not adding any merge commits to your branch
 - Open a pull request & wait for a review!🩵
 
-## Developing environment
+## Setting Up Your Build Environment
 
-After installing all dependencies with `yarn`, you can run
+### Build Requirements
+
+To build Vivify you need the following dependencies:-
+
+#### Arch Linux/Manjaro
 
 ```sh
-yarn dev
+sudo pacman -S --needed jq yarn make zip
 ```
 
-to run the development server for Vivify on port 3000 that will (1)
-automatically reload when you make changes to the code, and (2), unlike the
-installed version, not shut down when there are no connected clients.
+#### Fedora and derivatives
+
+```sh
+sudo dnf install jq yarn make zip
+```
+
+> [!TIP]
+> TODO: Mention linux nodejs issue and refer to following section on nodejs
+
+## Nodejs
+
+***TODO: Talk about nodejs linux broken etc.***
+
+## Building Vivify
+
+***TODO: Take build steps from readme.md***
 
-With the development server running, use
+## Running Vivify for Development
+
+Once you have built **Vivify** or installed it using the pre-built binaries, you
+can then run the **Vivify** server in development mode to try it out with
+live-updates as you are coding.
+
+Using `yarn dev` to run **Vivify** in dev mode will:-
+
+1. Run `vivify-server` on port `3000` instead of the usual port of `31622` so they
+   can be run side by side;
+2. Automatically reload when you make changes to the code; and
+3. Unlike the installed version, not shut down when there are no connected clients.
 
 ```sh
+# Run yarn to update any nodejs / npm package depenencies
+yarn
+
+# Start the Vivify server in dev mode
+yarn dev
+```
+
+With the development server running, use:-
+
+```sh
+# Connect an instance to your Vivify dev server
 yarn viv
 ```
 
@@ -37,6 +76,10 @@ You can find files to test Vivify's rendering/parsing capabilities in the
 [`tests/`](tests/) directory. Please make sure to add to this in case you add
 anything new related to this.
 
+## Troubleshooting
+
+***TODO: Common errors and build problems here?***
+
 ## Writing Markdown
 
 We use