docs: document issue with direnv and nix-shell on macOS (#15990) (#16015)

- @paulroub's contribution to `CONTRIBUTING.md` adds a workaround and a
link to the direnv issue
- some editing to the format/layout of the doc

---------

Co-authored-by: Paul Roub <paul@roub.net>

docs/CONTRIBUTING.md

@@ -2,11 +2,17 @@
 
 ## Requirements
 
-We recommend using the [Nix](https://nix.dev/) package manager as it makes any
-pain related to maintaining dependency versions
-[disappear](https://nixos.org/guides/how-nix-works). Once nix
-[has been installed](https://nixos.org/download.html) the development
-environment can be _manually instantiated_ through the `nix-shell` command:
+<div class="tabs">
+
+We recommend that you use [Nix](https://nix.dev/) package manager to
+[maintain dependency versions](https://nixos.org/guides/how-nix-works).
+
+### Nix
+
+1. [Install Nix](https://nix.dev/install-nix#install-nix)
+
+1. After you've installed Nix, instantiate the development with the `nix-shell`
+   command:
 
    ```shell
    cd ~/code/coder
@@ -21,10 +27,9 @@ copying path '/nix/store/v2gvj8whv241nj4lzha3flq8pnllcmvv-ignore-5.2.0.tgz' from
    ...
    ```
 
-If [direnv](https://direnv.net/) is installed and the
-[hooks are configured](https://direnv.net/docs/hook.html) then the development
-environment can be _automatically instantiated_ by creating the following
-`.envrc`, thus removing the need to run `nix-shell` by hand!
+1. Optional: If you have [direnv](https://direnv.net/) installed with
+   [hooks configured](https://direnv.net/docs/hook.html), you can add `use nix`
+   to `.envrc` to automatically instantiate the development environment:
 
    ```shell
    cd ~/code/coder
@@ -33,8 +38,8 @@ direnv allow
    ```
 
    Now, whenever you enter the project folder,
-[`direnv`](https://direnv.net/docs/hook.html) will prepare the environment for
-you:
+   [`direnv`](https://direnv.net/docs/hook.html) will prepare the environment
+   for you:
 
    ```shell
    cd ~/code/coder
@@ -46,7 +51,12 @@ direnv: export +AR +AS +CC +CONFIG_SHELL +CXX +HOST_PATH +IN_NIX_SHELL +LD +NIX_
    🎉
    ```
 
-Alternatively if you do not want to use nix then you'll need to install the need
+   - If you encounter a `creating directory` error on macOS, check the
+     [troubleshooting](#troubleshooting) section below.
+
+### Without Nix
+
+Alternatively if you do not want to use Nix then you'll need to install the need
 the following tools by hand:
 
 - Go 1.18+
@@ -73,7 +83,9 @@ the following tools by hand:
 - `pandoc`
   - on macOS, run `brew install pandocomatic`
 
-### Development workflow
+</div>
+
+## Development workflow
 
 Use the following `make` commands and scripts in development:
 
@@ -203,8 +215,7 @@ This helps in naming the dump (e.g. `000069` above).
 
 ### Documentation
 
-Our style guide for authoring documentation can be found
-[here](./contributing/documentation.md).
+Visit our [documentation style guide](./contributing/documentation.md).
 
 ### Backend
 
@@ -334,3 +345,17 @@ The
 [`release/experimental`](https://github.com/coder/coder/issues?q=sort%3Aupdated-desc+label%3Arelease%2Fexperimental)
 label can be used to move the note to the bottom of the release notes under a
 separate title.
+
+## Troubleshooting
+
+### Nix on macOS: `error: creating directory`
+
+On macOS, a [direnv bug](https://github.com/direnv/direnv/issues/1345) can cause
+`nix-shell` to fail to build or run `coder`. If you encounter
+`error: creating directory` when you attempt to run, build, or test, add a
+`mkdir` line to your `.envrc`:
+
+```shell
+use nix
+mkdir -p "$TMPDIR"
+```