diff --git a/docs/README.md b/docs/README.md
index 5c94e70ae..aba4ad4da 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,6 +1,9 @@
 # Build instructions
 
-To build the docs you must use Python 3.11.
+To build the docs you must install the following requirements:
+
+- GNU Make (Linux + Mac only)
+- Python 3.11
 
 To create a build environment run the following commands:
 ```python
@@ -9,7 +12,7 @@ source .venv/bin/activate
 pip install -r docs/requirements.txt
 
 cd docs
-make html
+make html # .\make html on Windows
 ```
 
 # Example Headers
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 12196b605..676021b0f 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -15,6 +15,7 @@ Welcome to rez's documentation!
    getting_started
    basic_concepts
    building_packages
+   releasing_packages
    context
    variants
    guides/index
diff --git a/docs/source/releasing_packages.rst b/docs/source/releasing_packages.rst
new file mode 100644
index 000000000..a75ad5f1d
--- /dev/null
+++ b/docs/source/releasing_packages.rst
@@ -0,0 +1,27 @@
+==================
+Releasing packages
+==================
+
+Rez packages can be built and deployed to the :data:`release_packages_path`
+using the :ref:`rez-release` tool. This tool performs the following actions:
+
+* All :doc:`actions <building_packages>` that the ``rez-build`` tool performs.
+* Executes all configured :data:`release_hooks`.
+* Executes all configured :gh-rez:`src/rezplugins/release_vcs` plugins.
+
+When to release vs build
+============================
+Packages *can* be installed to the :data:`release_packages_path` manually
+by running :option:`rez-build -i --prefix /path/to/repo <rez-build --prefix>`, so why would you use
+``rez-release``?
+
+Well, here are a few benefits of ``rez-release``:
+
+* The package will automatically go to the configured :data:`release_packages_path`, whereas :ref:`rez-build` will go to the :data:`local_packages_path` by default.
+* Tests being run by with the :ref:`rez-test` tool can run specifically prior to release, ensuring that releases pass any configured tests first.
+* Automatic sanity checks to ensure local repo is ready for release.
+* Automatic VCS tagging.
+* Many :ref:`helpful package attributes <release-package-attributes>` are automatically added to the released package definition file.
+
+If you're working locally, it these additional steps and checks may slow you
+down, so it may be better to stick with :ref:`rez-build`.
diff --git a/src/rez/rezconfig.py b/src/rez/rezconfig.py
index ca1f14b15..50749f1c4 100644
--- a/src/rez/rezconfig.py
+++ b/src/rez/rezconfig.py
@@ -824,7 +824,7 @@
 # a plugin listed here is not present, a warning message is printed. Note that a
 # release hook plugin being loaded does not mean it will run. It needs to be
 # listed here as well. Several built-in release hooks are available, see
-# rezplugins/release_hook.
+# :gh-rez:`src/rezplugins/release_hook`.
 release_hooks = []
 
 # Prompt for release message using an editor. If set to False, there will be