diff --git a/README.md b/README.md
index d2f53ae24..4dc18eb71 100644
--- a/README.md
+++ b/README.md
@@ -75,9 +75,11 @@ curl -fsSL https://d2lang.com/install.sh | sh -s --
 
 We have precompiled binaries on the [releases](https://github.com/terrastruct/d2/releases)
 page for macOS and Linux. For both amd64 and arm64. We will release package manager
-distributions like .rpm, .deb soon. d2 is on homebrew with our tap. See [./docs/INSTALL.md](./docs/INSTALL.md).
+distributions like .rpm, .deb soon. D2 is on Homebrew with our tap (the install script
+uses this automatically if it detects you have `brew`). See
+[./docs/INSTALL.md](./docs/INSTALL.md).
 
-We'll have a docker image soon too.
+Docker image coming soon.
 
 To uninstall:
 
diff --git a/docs/INSTALL.md b/docs/INSTALL.md
index 220b79dab..0dda53b17 100644
--- a/docs/INSTALL.md
+++ b/docs/INSTALL.md
@@ -1,13 +1,13 @@
 # install
 
-This file documents all the ways by which you can install d2.
+This file documents all the ways by which you can install D2.
 
 <!-- toc -->
 
 - [install.sh](#installsh)
-- [Standalone](#standalone)
 - [macOS (Homebrew)](#macos-homebrew)
-- [From Source](#from-source)
+- [Standalone](#standalone)
+- [From source](#from-source)
 
 <!-- tocstop -->
 
@@ -21,31 +21,41 @@ curl -fsSL https://d2lang.com/install.sh | sh -s -- --dry-run
 curl -fsSL https://d2lang.com/install.sh | sh -s --
 ```
 
-For help on the terminal run including the supported package managers
-and detection methods see:
+For help on the terminal run, including the supported package managers and detection
+methods:
 
 ```sh
 curl -fsSL https://d2lang.com/install.sh | sh -s -- --help
 ```
 
+## macOS (Homebrew)
+
+If you're on macOS, you can alternatively install with `brew`. (the install script above
+does this automatically if you have `brew` installed).
+
+```sh
+brew tap terrastruct/d2
+brew install d2
+```
+
 ## Standalone
 
-We publish standalone release archives with every release on github.
-Download the `.tar.gz` release for your OS/ARCH combination and then run:
+We publish standalone release archives with every release on Github.
+Download the `.tar.gz` release for your OS/ARCH combination and then run the following
+inside the extracted directory to install:
 
 ```sh
 make install
 ```
 
-Inside the extracted directory to install.
+Run the following to uninstall:
 
 ```sh
 make uninstall
 ```
 
-To uninstall. You will be prompted for sudo/su/doas if root permissions
-are required for installation. You can control the unix hierarchy installation
-path with `PREFIX=`. For example:
+You will be prompted for sudo/su/doas if root permissions are required for installation.
+You can control the Unix hierarchy installation path with `PREFIX=`. For example:
 
 ```
 # Install under ~/.local.
@@ -59,16 +69,10 @@ The install script places the standalone release into `$PREFIX/lib/d2/d2-<versio
 and we recommend doing the same with manually installed releases so that you
 know where the release directory is for easy uninstall.
 
-## macOS (Homebrew)
 
-For macOS you may install as so:
+## From source
 
-```sh
-brew tap terrastruct/d2
-brew install d2
-```
-
-## From Source
+Alternatively, you can always install from source:
 
 ```sh
 go install oss.terrastruct.com/d2/cmd/d2@latest