Update "Getting started" part of the book (#4938)

* refactor index.md

* move philosophy.md into index.md

* clean up the 'getting started' topic

move how-to's to the how-to section

* cleaner titles

* move prerequisites to the install.md page

* hardware.md: small refactor

* improve quick-start.md

* refactor eth1.md

* refactor validating guide

* reverse the order of BN and LC in the table

* pi-guide.md: minor edit

* Apply suggestions from code review

Co-authored-by: tersec <[email protected]>

* make link texts more concrete

* remove comparison to other clients

* add some more explanations to `build.md`

* change 'days' to 'hours'

---------

Co-authored-by: tersec <[email protected]>

Author: narimiran

docs/the_nimbus_book/mkdocs.yml

@@ -43,24 +43,22 @@ markdown_extensions:
       toc_depth: 3
 
 nav:
-  - About:
+  - Home:
     - 'index.md'
-    - 'philosophy.md'
 
   - Getting started:
     - 'quick-start.md'
     - 'run-a-validator.md'
-    - 'migration.md'
-    - 'metrics-pretty-pictures.md'
-    - 'pi-guide.md'
     - 'el-light-client.md'
+    - 'pi-guide.md'
 
   - How-to:
     - Beacon node:
       - 'install.md'
       - 'build.md'
       - 'start-syncing.md'
       - 'trusted-node-sync.md'
+      - 'migration.md'
 
     - Validator:
       - 'deposit.md'
@@ -81,6 +79,7 @@ nav:
       - 'goerli-eth.md'
       - 'beacon-node-systemd.md'
       - 'log-rotate.md'
+      - 'metrics-pretty-pictures.md'
       - 'database-backup.md'
       - 'email-notifications.md'
       - 'profits.md'

docs/the_nimbus_book/src/build.md

@@ -9,68 +9,7 @@ The build process itself is simple and fully automated, but may take a few minut
 
 ## Prerequisites
 
-!!! tip
-    If you are planning to use the precompiled binaries, you can skip this section and go straight to the [binaries](./binaries.md)!
-
-When building from source, you will need additional build dependencies to be installed:
-
-- Developer tools (C compiler, Make, Bash, Git)
-- [CMake](https://cmake.org/)
-
-<!-- TODO: Please test whether the instructions below are correct. I think we are missing some dependencies on Windows. -->
-<!--       Microsoft offer virtual machines that you can use for testing here: -->
-<!--       https://developer.microsoft.com/en-us/windows/downloads/virtual-machines/ -->
-
-=== "Linux"
-
-    On common Linux distributions the dependencies can be installed with
-
-    ```sh
-    # Debian and Ubuntu
-    sudo apt-get install build-essential git cmake
-
-    # Fedora
-    dnf install @development-tools cmake
-
-    # Archlinux, using an AUR manager
-    yourAURmanager -S base-devel cmake
-    ```
-
-=== "macOS"
-
-    With [Homebrew](https://brew.sh/):
-
-    ```sh
-    brew install cmake
-    ```
-
-=== "Windows"
-
-    To build Nimbus on Windows, the MinGW-w64 build environment is recommended.
-
-    Install Mingw-w64 for your architecture using the "[MinGW-W64 Online Installer](https://sourceforge.net/projects/mingw-w64/files/)":
-
-    1. Select your architecture in the setup menu (`i686` on 32-bit, `x86_64` on 64-bit).
-    2. Set threads to `win32`.
-    3. Set exceptions to "dwarf" on 32-bit and "seh" on 64-bit.
-    4. Change the installation directory to `C:\mingw-w64` and add it to your system PATH in `"My Computer"/"This PC" -> Properties -> Advanced system settings -> Environment Variables -> Path -> Edit -> New -> C:\mingw-w64\mingw64\bin` (`C:\mingw-w64\mingw32\bin` on 32-bit).
-
-    !!! note
-        If the online installer isn't working you can try installing `mingw-w64` through [MSYS2](https://www.msys2.org/).
-
-    Install [Git for Windows](https://gitforwindows.org/) and use a "Git Bash" shell to clone and build `nimbus-eth2`.
-
-=== "Android"
-
-    - Install the [Termux](https://termux.com) app from FDroid or the Google Play store
-    - Install a [PRoot](https://wiki.termux.com/wiki/PRoot) of your choice following the instructions for your preferred distribution.
-    Note, the Ubuntu PRoot is known to contain all Nimbus prerequisites compiled on Arm64 architecture (the most common architecture for Android devices).
-
-    Assuming you use Ubuntu PRoot
-
-    ```sh
-    apt install build-essential git
-    ```
+Make sure you have all needed [build prerequisites](./install.md#build-prerequisites).
 
 ## Building the node
 
@@ -91,3 +30,19 @@ make -j4 nimbus_beacon_node
 
 !!! tip
     Omit `-j4` on systems with 4GB of memory or less.
+
+This step can take several minutes.
+After it has finished, you can check if the installation was successful by running:
+
+```sh
+build/nimbus_beacon_node --help
+```
+
+If you see the command-line options, your installation was successful!
+Otherwise, don't hesitate to reach out to us in the `#helpdesk` channel of [our discord](https://discord.gg/j3nYBUeEad).
+
+
+
+## Keeping Nimbus updated
+
+When you decide to upgrade Nimbus to a newer version, make sure to follow the [keeping updated guide](./keep-updated.md).

docs/the_nimbus_book/src/el-light-client.md

@@ -1,4 +1,4 @@
-# Run the light client
+# Light client
 
 !!! warning
     The light client is currently in BETA and details around running it may change.
@@ -12,13 +12,13 @@ Since the merge 🐼, execution clients can no longer run standalone.
 
 Compared to a full beacon node, a light client has several advantages and disadvantages.
 
-| Feature | Light Client | Beacon Node |
+| Feature | Beacon Node | Light Client |
 | -- | -- | -- |
-| Disk usage | **<1MB** | ~70GB |
-| Bandwidth | **TBD (low)** | *TBD* |
-| Sync time | **Seconds** | Days |
-| Head delay | 4/3 slot (15 s) | **None** |
-| Security | Light | **Full** |
+| Disk usage | ~70GB | **<1MB** |
+| Bandwidth | *TBD* | **TBD (low)** |
+| Sync time | Hours | **Seconds** |
+| Head delay | **None** | 4/3 slot (15 s) |
+| Security | **Full** | Light |
 
 Light clients delegate full validation to other network participants and operate under a honest supermajority (> 2/3) assumption among elected participants.
 Due to this delegation, light clients are typically behind by ~4/3 slots (~15 seconds on Ethereum mainnet).

docs/the_nimbus_book/src/eth1.md

@@ -1,16 +1,15 @@
 # Run an execution client
 
-In order to perform validation duties, you need to also be running an execution client — at least one for each beacon node.
+In order to perform validation duties, you **must have** an execution client running — at least one for each beacon node.
+Relying on third-party services such as Infura, Alchemy and Pocket is no longer possible.
+Sharing the same execution client between multiple beacon nodes is not supported.
 
-Nimbus has been tested all major execution clients, see the [execution client comparison](https://ethereum.org/en/developers/docs/nodes-and-clients/#execution-clients) for more information.
-
-!!! warning
-    You need to run your own execution client.
-    Relying on third-party services such as Infura, Alchemy and Pocket is no longer possible.
-    Sharing the same execution client between multiple beacon nodes is not supported.
+Nimbus has been tested with all major execution clients.
+See the [execution client comparison](https://ethereum.org/en/developers/docs/nodes-and-clients/#execution-clients) for more information.
 
 !!! info
-    Syncing an execution client may take hours or even days, depending on your hardware!
+    Syncing an execution client **may take hours or even days**, depending on your hardware!
+
 
 ## Steps
 

docs/the_nimbus_book/src/hardware.md

@@ -9,11 +9,15 @@ The recommended system requirements for running the Nimbus beacon node are:
 | Disk space | 200GB |
 | Network    | Reliable broadband |
 
-!!! note "Execution client"
-    In addtion to the beacon node, you will need to run an [execution client](./eth1.md).
-    Check the documentation of the client of choice and add them to the above requirements.
 
-    Broadly, to run both an execution and a consensus client on the same machine, we recommend a **2 TB** SSD drive and **8 GB RAM**.
+### Execution client
 
-!!! note "Minimal requirements"
-    Nimbus has been optimized to also run well on hardware significantly less powerful than the recommended system requirements — the more validators you run on the same node, the more hardware resources and network bandwidth will it will use.
+In addition to the beacon node, you will need to run an [execution client](./eth1.md).
+Check the documentation of the client of choice and add them to the above requirements.
+
+Broadly, to run both an execution and a consensus client on the same machine, we recommend a **2 TB** SSD and **16 GB RAM**.
+
+
+### Minimal requirements
+
+Nimbus has been optimized to also run well on hardware significantly less powerful than the recommended system requirements — the more validators you run on the same node, the more hardware resources and network bandwidth will it will use.

docs/the_nimbus_book/src/index.md

@@ -1,19 +1,13 @@
 # The Nimbus Guide
 
-!!! note ""
-    Eager to get started?
-    The [quickstart guide](./quick-start.md) is for you.
-
-    Coming from a different client?
-    Check out the [migration guide](./migration.md).
-
 Nimbus is a client for the Ethereum network that is [lightweight](https://our.status.im/ethereum-is-green/), [secure](./audit.md) and [easy to use](./run-a-validator.md).
 
-Its efficiency and low resource consumption allows it to perform well on all kinds of systems: ranging from Raspberry Pi's and mobile devices — where it contributes to low power consumption and security — to powerful servers where it leaves resources free to perform other tasks, such as running an [execution node](./eth1.md).
+Its efficiency and low resource consumption allows it to perform well on all kinds of systems: ranging from Raspberry Pi and mobile devices — where it contributes to low power consumption and security — to powerful servers where it leaves resources free to perform other tasks, such as running an [execution node](./eth1.md).
 
 This book describes the consensus layer client, [`nimbus-eth2`](https://github.com/status-im/nimbus-eth2).
 An execution client, [nimbus-eth1](https://github.com/status-im/nimbus-eth2), is also under development.
 
+
 ## Feature highlights
 
 * [Beacon node](./quick-start.md) with integrated validator client, slashing protection and doppelganger detection
@@ -24,6 +18,36 @@ An execution client, [nimbus-eth1](https://github.com/status-im/nimbus-eth2), is
 * [External block builder](./external-block-builder.md) (PBS / mev-boost) support with execution client fallback
 * [Light consensus client](./el-light-client.md) for running an execution client without a full beacon node
 
+
+## Design goals
+
+One of our most important design goals is an application architecture that makes it **simple to embed Nimbus into other software.**
+
+Another goal is to **minimize reliance on third-party software.**
+
+A third one is for the application binary to be as **lightweight as possible in terms of resources used.**
+
+### Integration with Status
+
+<blockquote class="twitter-tweet"><p lang="en" dir="ltr">I can&#39;t wait to run Nimbus straight from Status Desktop <a href="https://twitter.com/hashtag/hyped?src=hash&amp;ref_src=twsrc%5Etfw">#hyped</a></p>&mdash; JARRAÐ HOPΞ (@jarradhope) <a href="https://twitter.com/jarradhope/status/1293473249347555334?ref_src=twsrc%5Etfw">August 12, 2020</a></blockquote> <script async src="https://platform.twitter.com/widgets.js" charset="utf-8"></script>
+
+As part of our first design goal, our primary objective here is for Nimbus to be tightly integrated into the [Status messaging app](https://status.im/).
+
+Our dream is for you to be able to run and monitor your validator straight from Status desktop.
+
+
+## Book contents
+
+You can read this book from start to finish, or you might want to read just specific topics you're interested in:
+
+* If you're eager to get started, the [quickstart guide](./quick-start.md) is for you.
+* Coming from a different client? Check out the [migration guide](./migration.md).
+* Visualize the important metrics with [Grafana and Prometheus](./metrics-pretty-pictures.md).
+* Interested in becoming a validator? Follow the [validator guide](./run-a-validator.md).
+* If you're not planning on becoming a validator, you can run the [light client](./el-light-client.md).
+
+
+
 ## Get in touch
 
 Need help with anything?

docs/the_nimbus_book/src/install.md

@@ -8,8 +8,68 @@ Check that your machine matches the [minimal system requirements](./hardware.md)
 
 ## Build prerequisites
 
-You will need to install developer tools (C compiler, Make, Bash, Git) and [CMake](https://cmake.org/).
-See the [build guide](./build.md).
+!!! tip
+    If you are planning to use the precompiled binaries, you can skip this section and go straight to the [binaries](./binaries.md)!
+
+When building from source, you will need additional build dependencies to be installed:
+
+- Developer tools (C compiler, Make, Bash, Git)
+- [CMake](https://cmake.org/)
+
+<!-- TODO: Please test whether the instructions below are correct. I think we are missing some dependencies on Windows. -->
+<!--       Microsoft offer virtual machines that you can use for testing here: -->
+<!--       https://developer.microsoft.com/en-us/windows/downloads/virtual-machines/ -->
+
+=== "Linux"
+
+    On common Linux distributions the dependencies can be installed with:
+
+    ```sh
+    # Debian and Ubuntu
+    sudo apt-get install build-essential git cmake
+
+    # Fedora
+    dnf install @development-tools cmake
+
+    # Arch Linux, using an AUR manager
+    yourAURmanager -S base-devel cmake
+    ```
+
+=== "macOS"
+
+    With [Homebrew](https://brew.sh/):
+
+    ```sh
+    brew install cmake
+    ```
+
+=== "Windows"
+
+    To build Nimbus on Windows, the MinGW-w64 build environment is recommended.
+
+    Install Mingw-w64 for your architecture using the "[MinGW-W64 Online Installer](https://sourceforge.net/projects/mingw-w64/files/)":
+
+    1. Select your architecture in the setup menu (`i686` on 32-bit, `x86_64` on 64-bit).
+    2. Set threads to `win32`.
+    3. Set exceptions to "dwarf" on 32-bit and "seh" on 64-bit.
+    4. Change the installation directory to `C:\mingw-w64` and add it to your system PATH in `"My Computer"/"This PC" -> Properties -> Advanced system settings -> Environment Variables -> Path -> Edit -> New -> C:\mingw-w64\mingw64\bin` (`C:\mingw-w64\mingw32\bin` on 32-bit).
+
+    !!! note
+        If the online installer isn't working you can try installing `mingw-w64` through [MSYS2](https://www.msys2.org/).
+
+    Install [Git for Windows](https://gitforwindows.org/) and use a "Git Bash" shell to clone and build `nimbus-eth2`.
+
+=== "Android"
+
+    - Install the [Termux](https://termux.com) app from FDroid or the Google Play store
+    - Install a [PRoot](https://wiki.termux.com/wiki/PRoot) of your choice following the instructions for your preferred distribution.
+    Note, the Ubuntu PRoot is known to contain all Nimbus prerequisites compiled on Arm64 architecture (the most common architecture for Android devices).
+
+    Assuming you use Ubuntu PRoot:
+
+    ```sh
+    apt install build-essential git
+    ```
 
 ## Time