apply more of @gen2thomas suggestions

Author: soypat

content/docs/guides/selfbuild/bring-your-own-llvm.md

@@ -14,9 +14,16 @@ description: >
 | You are using Windows. |
 | Your Linux distribution (if you use Linux) does not ship the right LLVM version. |
 
+## System installed LLVM instructions
+
+### Installing LLVM
+
+See [troubleshooting](#troubleshooting) if running into issues during the instructions.
 
 Using a system-installed version of LLVM depends on your system, of course.
 
+#### Debian or Ubuntu
+
 For **Debian** or **Ubuntu** you can install LLVM by adding a new apt repository. For more information about this method, see [apt.llvm.org](https://apt.llvm.org/). *Before copying the command below, please replace `xxxxx` with your distribution's codename*.
 
 | Distro | Version | Codename |
@@ -42,46 +49,64 @@ sudo apt-get update
 sudo apt-get install clang-16 llvm-16-dev lld-16 libclang-16-dev
 ```
 
+#### MacOS
+
 For **MacOS**, you can install LLVM through [Homebrew](https://formulae.brew.sh/formula/llvm). The Clang/LLVM version from Apple is not supported by TinyGo.
 
 ```shell
 brew install llvm
 ```
+#### Fedora
 
 For **Fedora** users you can install LLVM from the repository. Note that the version of LLVM [varies by Fedora version](https://packages.fedoraproject.org/pkgs/llvm/llvm-libs/), for example Fedora 37 has LLVM 15.
 
 ```shell
 sudo dnf install llvm-devel lld-libs lld
 ```
 
-After LLVM has been installed, installing TinyGo should be as easy as running the following command:
+
+### Build TinyGo
+
+After LLVM has been installed, installing TinyGo should be as easy as running the following command from within the cloned `tinygo` repository (see [instructions on how to clone](./..)):
 
 ```shell
 go install
 ```
 
 You should now have a working TinyGo installation!
 
+Below is an example of running `tinygo version` and example output to check that
+TinyGo was installed correctly (copy only what's in front of the `$` sign to your terminal!):
+```shell
+$ tinygo version
+tinygo version 0.31.0-dev-d4189fec linux/amd64 (using go version go1.21.4 and LLVM version 16.0.1)
+```
+
+If not see the [troubleshooting](#troubleshooting) section.
+
 If you have gotten this far, please refer to [Additional requirements](./additional-requirements) to further set up TinyGo.
 
-## Final notes
+## Troubleshooting
 
 ### `go install` command inner workings
 The `go install` command will build the `tinygo` executable and store it to your currently set `$GOBIN` directory. A couple environment variables must be set for TinyGo to work after running this:
 
-* Your `GOBIN` should be set to where you want go binaries to be stored to. Below is an example (for linux systems)
-    ```shell
-    go env -w GOBIN=$HOME/local/bin
-    ```
-* The directory should exist! Below is a way to create the directory on linux.
-    ```shell
-    mkdir -p $HOME/local/bin
-    ```
-* Your $PATH environment variable should contain the directory so that you can run `tinygo` from the command line! A reliable way to achieve this can be found at the [Go install page](https://go.dev/doc/install#). For linux it consists of adding the line below to the bottom of your `/etc/profile` file (before the `exit 0`):
+* Your go environment variable `GOBIN` points to where executables are installed with the
+    `go install` command. An empty `GOBIN` variable will default to `$HOME/go/bin` path on Linux and MacOS (same as `~/go/bin` with bash).
+    You can check Go's environment variables with `go env`. `go env GOBIN` will print
+    only `GOBIN`'s value.
+ 
+* Your $PATH environment variable should contain the `GOBIN` directory so that you can run `tinygo` from the command line! A reliable way to achieve this can be found at the [Go install page](https://go.dev/doc/install#). For linux it consists of adding the line below to the bottom of your `/etc/profile` file (before the `exit 0`):
     ```
-    export PATH=$PATH:$HOME/local/bin
+    export PATH=$PATH:$HOME/go/bin
     ```
 
+### Debian LLVM repository manual addition
+If `sudo apt-get install clang-16 llvm-16-dev lld-16 libclang-16-dev` does not work you
+can try manually adding the repository. Run the following command and try the steps above again.
+```shell
+wget -O - https://apt.llvm.org/llvm-snapshot.gpg.key | sudo apt-key add -
+```
 
 ### GCC errors
 If you are getting an `gcc` or `g++ not found` error you most likely do not have a working C++ build environment. You'll need the `build-essential` package on Debian or `sudo dnf install make automake gcc gcc-c++` for Fedora based systems.

content/docs/guides/selfbuild/manual-llvm.md

@@ -75,7 +75,7 @@ This results in a `tinygo` binary in the `build` directory:
 
 ```shell
 $ ./build/tinygo version
-tinygo version 0.30.0 linux/amd64 (using go version go1.21 and LLVM version 16.0.0)
+tinygo version 0.31.0-dev-d4189fec linux/amd64 (using go version go1.21.4 and LLVM version 16.0.1)
 ```
 
 You have successfully built TinyGo from source. Congratulations!