Rework how the toolchains are explained (#739)

Author: athei

docs/knowledgebase/getting-started/index.md

@@ -3,22 +3,17 @@ title: Installation
 ---
 
 This page will guide you through the steps needed to prepare a computer for Substrate development.
-Since Substrate is built with [the Rust programming language](https://www.rust-lang.org/), the first
-thing you will need to do is prepare the computer for Rust development - these steps will vary based
-on the computer's operating system. Then, you can use the helpful utilities from the Rust toolchain
-to configure the Rust development environment - these steps will be the same for all the
-(Unix-based) operating systems discussed on this page.
-
-## Operating System-Dependent Set-Up
-
-Follow the steps for your computer's operating system before installing and configuring the Rust
-toolchain.
+As Substrate is built with [the Rust programming language](https://www.rust-lang.org/), the first
+thing you will need to do is prepare the development enviroment, these steps will vary based
+on the computer's operating system. You can utilize helpful utilities from the Rust toolchain
+to configure the Rust development environment. Note that these steps will be the same for all
+Unix-based operating systems discussed on this page.
 
 ### Unix-Based Operating Systems
 
-Substrate development is easiest on Unix-based operating systems, like macOS or Linux. The examples
+Substrate development is optimized for Unix-based operating systems like macOS or Linux. The examples
 in the Substrate [Tutorials](../../../../tutorials) and [Recipes](https://substrate.dev/recipes/)
-use Unix-style terminals to demonstrate how to interact with Substrate from the command line.
+use the terminal to demonstrate how to interact with Substrate from the command line.
 
 #### macOS
 
@@ -30,7 +25,7 @@ Open the Terminal application and execute the following commands:
 
 # Make sure Homebrew is up-to-date and install some dependencies
 brew update
-brew install openssl cmake llvm
+brew install openssl cmake
 ```
 
 #### Ubuntu/Debian
@@ -59,13 +54,14 @@ Please refer to the separate [guide for Windows users](windows-users.md).
 
 ## Rust Developer Environment
 
-This guide uses [`rustup`](https://rustup.rs/) to help manage the Rust toolchain; first, install and
+This guide uses [`rustup`](https://rustup.rs/) to help manage the Rust toolchain. First install and
 configure `rustup`:
 
 ```bash
 # Install
 curl https://sh.rustup.rs -sSf | sh
-# Configure
+# Add the rust compiler and other tools to your PATH.
+# Make sure to add this to your shell startup script, too.
 source ~/.cargo/env
 ```
 
@@ -79,62 +75,75 @@ rustup default stable
 
 Substrate uses [WebAssembly](https://webassembly.org/) (Wasm) to produce portable blockchain
 runtimes. You will need to configure your Rust compiler to use
-[`nightly` builds](https://doc.rust-lang.org/book/appendix-07-nightly-rust.html) to allow you to
-compile Rust code to the Wasm target.
+[`nightly` builds](https://doc.rust-lang.org/book/appendix-07-nightly-rust.html) to allow
+compiled substrate compatible runtimes to Wasm.
 
 #### Rust Nightly Toolchain
 
-Developers that are building _with_ Substrate (as opposed to the developers building Substrate
-_itself_) should use a specific Rust nightly version that is known to be compatible with the version
-of Substrate they are using. Use Rustup to install the correct nightly:
+Because the nightly toolchain is a moving target and receives daily changes the chance
+that some of them break the substrate build from time to time is non-negligible.
+
+Therefore it is advised to use a fixed nightly version rather than the latest one to
+build the runtime. You can install a specific version using this command:
 
 ```bash
 rustup install nightly-<yyyy-MM-dd>
 ```
 
+---
+**NOTE**
+Due to a regression in the rust compiler, using the newest rust nightly for compiling
+the runtime will result in compilation errors. Therefore, it is advised to use the
+following version until this issue is resolved:
+
+```bash
+rustup install nightly-2010-10-06
+```
+
+---
+
 #### Wasm Toolchain
 
-Now, configure the nightly version to work with the Wasm compilation target:
+Now, configure the choosen nightly version to work with the Wasm compilation target:
 
 ```bash
 rustup target add wasm32-unknown-unknown --toolchain nightly-<yyyy-MM-dd>
 ```
 
 #### Specifying Nightly Version
 
-If you are working with a Substrate-based project that does not include a toolchain file, you can
-use the Rust build and package manager, [Cargo](https://doc.rust-lang.org/cargo/), to specify a
-nightly version:
+When a Substrate based project builds its included runtime it picks the latest
+installed nightly version by default. If the nightly version is incompatible
+you can override that decision by setting the `WASM_BUILD_TOOLCHAIN` environment variable
+when building the project by using the following command:
 
 ```bash
-cargo +nightly-<yyyy-MM-dd> ...
+WASM_BUILD_TOOLCHAIN=nightly-<yyyy-MM-dd> cargo build
 ```
 
+Note that this builds only the runtime with the specified toolchain. The rest of project will
+be compiled with your default toolchain which is usually the latest installed stable toolchain.
+
 #### Latest Nightly
 
-Developers that are building Substrate _itself_ should always uses the latest version of Rust stable
-and nightly for compilation. To ensure your Rust compiler is always up to date, you should run:
+If you want to build the runtime with the latest nightly compiler which should **generally** be
+possible you can install the unspecific `nightly` toolchain:
 
 ```bash
-rustup update
-rustup update nightly
+rustup install nightly
 rustup target add wasm32-unknown-unknown --toolchain nightly
 ```
 
-**It may be necessary to occasionally rerun `rustup update`** if a change in the upstream Substrate
-codebase depends on a new feature of the Rust compiler.
-
-#### Downgrading Rust Nightly
-
-If your computer is configured to use the latest Rust nightly and you would like to downgrade to a
-specific nightly version, follow these steps:
+This toolchain is not tied to a specific version and will be updated just as the
+`stable` toolchain:
 
 ```bash
-rustup uninstall nightly
-rustup install nightly-<yyyy-MM-dd>
-rustup target add wasm32-unknown-unknown --toolchain nightly-<yyyy-MM-dd>
+rustup update
 ```
 
+**It may be necessary to occasionally rerun `rustup update`** if a change in the upstream Substrate
+codebase depends on the most recent version of the Rust compiler.
+
 ## Test Your Set-Up
 
 The best way to ensure that you have successfully prepared a computer for Substrate development is