diff --git a/docs/the_nimbus_book/src/SUMMARY.md b/docs/the_nimbus_book/src/SUMMARY.md
index 3e20e3bec..cb0c483d4 100644
--- a/docs/the_nimbus_book/src/SUMMARY.md
+++ b/docs/the_nimbus_book/src/SUMMARY.md
@@ -2,9 +2,10 @@
 
 - [Introduction](./intro.md)
 - [Installation](./install.md)
-- [Running the beacon node](./beacon_node.md)
-- [Becoming a Validator](./validator.md)
+- [Become a Medalla validator](./medalla.md)
+- [Run the beacon node](./beacon_node.md)
+- [Become a validator (custom)](./validator.md)
 - [API](./api.md)
-- [Advanced Usage for Developers](./advanced.md)
+- [Advanced usage for developers](./advanced.md)
 - [FAQs](./faq.md)
 - [Contribute](./contribute.md)
diff --git a/docs/the_nimbus_book/src/beacon_node.md b/docs/the_nimbus_book/src/beacon_node.md
index a778d0399..5df9e739b 100644
--- a/docs/the_nimbus_book/src/beacon_node.md
+++ b/docs/the_nimbus_book/src/beacon_node.md
@@ -1,43 +1,52 @@
 # The beacon node
 
-The beacon node application connects to an Ethereum 2 network, manages the block chain and provides API's to interact with the beacon chain.
+The beacon node application connects to the eth2 network, manages the blockchain, and provides API's to interact with the beacon chain.
 
-You can run the beacon node without being a validator - doing so will allow you to sync the network and access its latest state.
+You can run the beacon node without being a validator - doing so allows you to sync the network and access its latest state.
 
 ## Prerequisites
 
-Before compiling and running the application, make sure you've completed the [installation guidelines](./install.md) for the prerequisites.
+Before compiling and running the application, make sure you've gone through the [installation guidelines](./install.md).
 
 ## Running the node
 
-When running the beacon node, you connect to a specific ethereum 2 network - this may be a private network or a public testnet like [altona](https://github.com/goerli/altona/tree/master/altona).
+When running the beacon node, you connect to a specific ethereum 2 network - this may be a private network or a public testnet like [Medalla](https://github.com/goerli/medalla/).
 
 When running the node for the first time, you need to specify network parameters, boot nodes and genesis information. This information can typically be found in the [eth2 testnets](https://github.com/eth2-clients/eth2-testnets) repository. This information is automatically downloaded when using the simplified startup.
 
-Once the beacon node is running, it will first connect to the boot nodes in the network, look for more peers and start syncing the chain. Once sync is complete, it will keep following the head of the chain and can be interacted with through the [API](./api.md).
+Once the beacon node is running, it will first connect to the boot nodes in the network, look for more peers and start syncing the chain. Once the sync is complete, it will keep following the head of the chain (you can interact with it through the [API](./api.md).
 
-Before running the beacon node, it is important that computer has the correct time set - preferably from a trusted time source (this can be an NTP server you trust, GPS time or any other precise source of time).
+Before running the beacon node, it's important that your computer is set to the correct time - preferably using a trusted time source (this can be an NTP server you trust, GPS time or another precise source of time) -- however don't worry if you're unsure of how to do this, it isn't essential for testnet purposes.
 
-To start syncing the `altona` network, run the build process. When asked for a key, just press enter.
+### Syncing
+
+To start syncing the `medalla` network:
+
+
+#### 1. Clone the nim beacon chain repository
 
 ```
-$ make altona
+git clone https://github.com/status-im/nim-beacon-chain
+cd nim-beacon-chain
+```
+
+#### 2. Run the build process
+
+```
+make medalla
 
 # Build output...
 
-Please enter your Goerli Eth1 private key in hex form (e.g. 0x1a2...f3c) in order to become a validator (you'll need access to 32 GoETH).
-Hit Enter to skip this.
->
 ```
 
-Hit enter above - you will be prompted again if you want to become a validator. Beacon node will launch and start syncing.
+This will build Nimbus and its dependencies, and connect you to Medalla.
+You should see that the beacon node has launched and started syncing.
 
 ```
-INF 2020-07-03 15:28:15+02:00 Starting beacon node                       topics="beacnde" tid=176865 file=beacon_node.nim:866 SECONDS_PER_SLOT=12 SLOTS_PER_EPOCH=32 SPEC_VERSION=0.12.1 cat=init dataDir=/home/arnetheduck/status/nim-beacon-chain/build/data/shared_altona_0 finalizedRoot=72e7b21c finalizedSlot=20064 headRoot=f92bf720 headSlot=20142 nim="Nim Compiler Version 1.2.2 [Linux: amd64] (be34b5ab)" pcs=start_beacon_node timeSinceFinalization=-108322 version="0.5.0 (c64737e)"
+INF 2020-07-03 15:28:15+02:00 Starting beacon node                       topics="beacnde" tid=176865 file=beacon_node.nim:866 SECONDS_PER_SLOT=12 SLOTS_PER_EPOCH=32 SPEC_VERSION=0.12.1 cat=init dataDir=/home/arnetheduck/status/nim-beacon-chain/build/data/shared_medalla_0 finalizedRoot=72e7b21c finalizedSlot=20064 headRoot=f92bf720 headSlot=20142 nim="Nim Compiler Version 1.2.2 [Linux: amd64] (be34b5ab)" pcs=start_beacon_node timeSinceFinalization=-108322 version="0.5.0 (c64737e)"
 
 
  peers: 7 ❯ finalized: 3a806c9f:634 ❯ head: b364f8e9:636:29 ❯ time: 909:7 (29095)              ETH: 0.0
-
 ```
 
 ### Status bar
@@ -60,7 +69,7 @@ Nimbus includes metrics support using the Prometheus format. To enable it, you n
 
 ```
 # Compile with insecure features enabled
-make NIMFLAGS="-d:insecure" altona
+make NIMFLAGS="-d:insecure" medalla
 ```
 
 ## Command line options
@@ -112,7 +121,7 @@ The following options are available:
 
 Available sub-commands:
 
-beacon_node_shared_altona_0 createTestnet [OPTIONS]...
+beacon_node_shared_medalla_0 createTestnet [OPTIONS]...
 
 The following options are available:
 
@@ -128,7 +137,7 @@ The following options are available:
      --with-genesis-root       Include a genesis root in 'network.json'.
      --output-bootstrap-file   Output file with list of bootstrap nodes for the network.
 
-beacon_node_shared_altona_0 deposits [OPTIONS]... command
+beacon_node_shared_medalla_0 deposits [OPTIONS]... command
 
 The following options are available:
 
@@ -136,7 +145,7 @@ The following options are available:
 
 Available sub-commands:
 
-beacon_node_shared_altona_0 deposits create [OPTIONS]...
+beacon_node_shared_medalla_0 deposits create [OPTIONS]...
 
 Creates validator keystores and deposits.
 
@@ -151,7 +160,7 @@ The following options are available:
                                `deposits send` command to send the deposit transactions at your convenience
                                later.
 
-beacon_node_shared_altona_0 deposits send [OPTIONS]...
+beacon_node_shared_medalla_0 deposits send [OPTIONS]...
 
 Sends prepared deposits to the validator deposit contract.
 
@@ -161,15 +170,15 @@ The following options are available:
      --min-delay               Minimum possible delay between making two deposits (in seconds).
      --max-delay               Maximum possible delay between making two deposits (in seconds).
 
-beacon_node_shared_altona_0 deposits status
+beacon_node_shared_medalla_0 deposits status
 
 Displays status information about all deposits.
 
-beacon_node_shared_altona_0 wallets command
+beacon_node_shared_medalla_0 wallets command
 
 Available sub-commands:
 
-beacon_node_shared_altona_0 wallets create [OPTIONS]...
+beacon_node_shared_medalla_0 wallets create [OPTIONS]...
 
 Creates a new EIP-2386 wallet.
 
@@ -179,7 +188,7 @@ The following options are available:
      --next-account            Initial value for the 'nextaccount' property of the wallet.
      --out                     Output wallet file.
 
-beacon_node_shared_altona_0 wallets restore [OPTIONS]...
+beacon_node_shared_medalla_0 wallets restore [OPTIONS]...
 
 Restores a wallet from cold storage.
 
@@ -190,7 +199,7 @@ The following options are available:
                                guess the number by inspecting the latest beacon state.
      --out                     Output wallet file.
 
-beacon_node_shared_altona_0 wallets list
+beacon_node_shared_medalla_0 wallets list
 
 Lists details about all wallets.
 ```
diff --git a/docs/the_nimbus_book/src/install.md b/docs/the_nimbus_book/src/install.md
index 0c55cdf82..7f09fe767 100644
--- a/docs/the_nimbus_book/src/install.md
+++ b/docs/the_nimbus_book/src/install.md
@@ -1,18 +1,20 @@
 # Installation
 
-Beacon chain can run on Linux, macOS, Windows, and Android. At the moment, Nimbus has to be built from source.
+The Beacon chain can run on Linux, macOS, Windows, and Android. At the moment, Nimbus has to be built from source.
 
 ## Time
 
 The beacon chain relies on your computer having the correct time set, down to at most 0.5 seconds.
 
-It is recommended that you run a high quality time service on your computer such as:
+We recommended you run a high quality time service on your computer such as:
 
 * GPS
 * NTS (network time security, IETF draft)
 * Roughtime (google)
 
-As a minimum, you should run an NTP client on the server - NTP may easily be disrupted however.
+As a minimum, you should run an NTP client on the server.
+
+If that makes no sense to you, don't worry. For testnets, just making sure your computer is set at the correct time should be fine.
 
 ## External Dependencies
 
@@ -63,4 +65,4 @@ apt install build-essential git libpcre3-dev
 
 ## Next steps
 
-Once you've installed the prerequisites, you're ready to move on to launching the [beacon node](./beacon_node.md).
+Once you've installed the prerequisites, you're ready to move on to [running a validator on Medalla](./medalla.md).
diff --git a/docs/the_nimbus_book/src/intro.md b/docs/the_nimbus_book/src/intro.md
index 8157abb2a..68121c5b6 100644
--- a/docs/the_nimbus_book/src/intro.md
+++ b/docs/the_nimbus_book/src/intro.md
@@ -1,26 +1,31 @@
-# The nim-beacon-chain Book
+# The nim-beacon-chain book
 
-_Documentation for Nimbus Beacon Chain users and developers._
+_Documentation for Nimbus beacon chain users and developers._
 
-Nimbus beacon chain is a research implementation of the beacon chain component of the upcoming Ethereum Serenity upgrade, aka Eth2.
+The Nimbus beacon chain is a research implementation of the Beacon Chain – the core system level chain at the heart of Ethereum 2.0.
 
-- Open sourced at [github.com/status-im/nim-beacon-chain](https://github.com/status-im/nim-beacon-chain/tree/master).
-- Specification of our implementation can be found at [ethereum/eth2.0-specs](https://github.com/ethereum/eth2.0-specs/tree/v0.12.2#phase-0).
+- Open sourced at [github.com/status-im/nim-beacon-chain](https://github.com/status-im/nim-beacon-chain/tree/master)
+
+- Specification described at [ethereum/eth2.0-specs](https://github.com/ethereum/eth2.0-specs/tree/v0.12.2#phase-0)
+- [Annotated Specification](https://benjaminion.xyz/eth2-annotated-spec/phase0/beacon-chain/) 
+
+- [Become a Medalla validator](./medalla.md)
 
 ## Overview
 
 In this book, we will cover:
 
-1. [What is beacon chain](./faq.md#1-what-is-beacon-chain) and [what is Nimbus](./faq.md#4-what-is-nimbus) to equip you with some basic knowledge.
-2. [Installation steps](./install.md) outline the prerequisites to get started.
-3. [Running the beacon node](./beacon_node.md) describes how to run the beacon node software to sync the beacon chain.
-4. How to [become a validator](./validator.md) in Ethereum 2.0 as a user, for example on the Altona testnet.
-5. [API](./api.md) for monitoring your node through `http`.
+1. An introduction to the [beacon chain](./faq.md#1-what-is-beacon-chain) and [Nimbus](./faq.md#4-what-is-nimbus) to equip you with some basic knowledge.
+2. [Installation steps](./install.md) outlining the prerequisites to get started.
+3. [Become a Medalla validator](./medalla.md): If you generated your signing key using the eth2 launchpad, and wish to import it into the Nimbus client, this page is for you.
+3. How to [run the beacon node](./beacon_node.md) software to sync the beacon chain.
+4. How to generate keys, deposit, and [become a validator](./validator.md) in eth2.
+5. The [API](./api.md) for monitoring your node through `http`.
 6. [Advanced usage](./advanced.md) for developers.
 7. Common [questions and answers](./faq.md) to satisfy your curiosity.
 8. How to [contribute](./contribute.md) to this book.
 
-Feel free to give us feedback on how to improve as well as contribute to our book on github. :)
+Feel free to give us feedback on how to improve :)
 
 ## Get in touch
 
@@ -29,7 +34,7 @@ Need help with anything? Join us using [Status](https://join.status.im/nimbus-ge
 
 ## Disclaimer
 
-This documentation is assuming Nimbus is in its ideal state. The project is still under active development. Please submit Github issues if encountered any problem.
+This documentation assumes Nimbus is in its ideal state. The project is still under active development. Please submit a [Github issue](https://github.com/status-im/nim-beacon-chain/issues) if you come across a problem.
 
 <!-- > > > TODO:
 
diff --git a/docs/the_nimbus_book/src/medalla.md b/docs/the_nimbus_book/src/medalla.md
new file mode 100644
index 000000000..31ad868c6
--- /dev/null
+++ b/docs/the_nimbus_book/src/medalla.md
@@ -0,0 +1,83 @@
+# Become a Medalla validator
+
+This page will take you through how to become a validator on the eth2 testnet [Medalla](https://github.com/goerli/medalla).
+
+If you generated your signing key using the [eth2 launchpad](https://medalla.launchpad.ethereum.org/), and wish to import it into the Nimbus client, this page is for you.
+
+> If you haven't created your validator key yet, we recommend you go through the [launchpad first](https://medalla.launchpad.ethereum.org/). If you're not sure what the eth2 launchpad is, we recommend reading this [introductory post](https://blog.ethereum.org/2020/07/27/eth2-validator-launchpad/).
+
+## Prerequisites
+
+If this is your first time playing with Nimbus, make sure you [install our external dependencies](./install.md) first.
+
+This tutorial assumes basic knowledge of the [command line](https://www.learnenough.com/command-line-tutorial/basics#:~:text=Learn%20Enough%20Command%20Line%20to%20Be%20Dangerous%20is%20an%20introduction,broad%20an%20audience%20as%20possible.).
+
+## Validating
+
+To start validating on the `medalla` network:
+
+
+#### 1. Clone the nim beacon chain repository
+
+```
+git clone https://github.com/status-im/nim-beacon-chain
+cd nim-beacon-chain
+git checkout devel
+```
+
+#### 2. Build the beacon node
+```
+make beacon_node
+```
+
+*Patience... this may take a few minutes.*
+
+#### 3. Import keystore(s)
+
+```
+build/beacon_node deposits import  --data-dir=build/data/shared_medalla_0 <YOUR VALIDATOR KEYS DIRECTORY>
+```
+
+Replacing `<YOUR VALIDATOR KEYS DIRECTORY>` with the full pathname of your `validator_keys` directory.
+
+> Tip: run `pwd` in your `validator_keys` directory to print the full pathname to the console.
+
+You'll be asked to enter the password you created to encrypt your keystore(s) in the *Generate Keys* section of the Launchpad process. Don't worry, this is entirely normal. Your validator client needs both your keystore(s) and the password encrypting it to import your [keys](https://blog.ethereum.org/2020/05/21/keys/) (since it needs to decrypt the keystore in order to be able to use it to sign on your behalf).
+
+
+#### 4. Connect to Medalla
+
+```
+make medalla
+```
+
+This will build Nimbus and its dependencies, and connect you to Medalla.
+You should see that the beacon node has launched with your validator attached and is waiting for [genesis](https://hackmd.io/@benjaminion/genesis) to start:
+
+```
+WRN 2020-08-03 16:24:17.950+02:00 Validator not in registry (yet?)           topics="beacval" tid=11677993 file=validator_duties.nim:53 pubKey=a9c4df36
+INF 2020-08-03 16:24:17.951+02:00 Local validator attached                   tid=11677993 file=validator_pool.nim:21 pubKey=a9c4df36 validator=a9c4df36
+INF 2020-08-03 16:24:17.951+02:00 Local validators attached                  topics="beacval" tid=11677993 file=validator_duties.nim:61 count=1
+INF 2020-08-03 16:24:17.958+02:00 Starting beacon node                       topics="beacnde" tid=11677993 file=beacon_node.nim:875 version="0.5.0 (31b33907)" nim="Nim Compiler Version 1.2.6 [MacOSX: amd64] (bf320ed1)" timeSinceFinalization=81350 head=ebe49843:0 finalizedHead=ebe49843:0 SLOTS_PER_EPOCH=32 SECONDS_PER_SLOT=12 SPEC_VERSION=0.12.2 dataDir=build/data/shared_medalla_0 pcs=start_beacon_node
+NOT 2020-08-03 16:24:17.958+02:00 Waiting for genesis                        topics="beacnde" tid=11677993 file=beacon_node.nim:890 genesisIn=22h35m50s0ns
+```
+
+#### 5. Keep an eye on your validator
+
+If you deposited after the [genesis](https://hackmd.io/@benjaminion/genesis) state was decided (August 2nd 1300 UTC), your validators will have been put in a queue based on deposit time, and will slowly be inducted into the validator set after genesis. Getting through the queue may take a few hours or days.
+
+The best way to keep track of your validator's status is [medalla.beaconcha.in](https://medalla.beaconcha.in) (click on the orange magnifying glass at the very top and paste in its public key). 
+
+You can even [create an account](https://medalla.beaconcha.in/register) to add alerts and keep track it its [performance](https://medalla.beaconcha.in/dashboard).
+
+Finally, makes sure you stay on the lookout for any critical updates to Nimbus. This best way to do so is through our [discord](https://discord.com/invite/XRxWahP).
+
+Looking forward to seeing you on Medalla! 💛
+
+### A note on keys
+
+The Nimbus client will only ever import your signing key -- in any case, if you used the deposit launchpad, this is the only key you should have (you can generate the withdrawal key from your mnemonic when you wish to withdraw). The keys your Nimbus client has access to are stored in the `build/data/shared_medalla_0/` folder, under `secrets` and `validators`.
+
+The `secrets` folder contains the common secret that gives you access to all your validator keys. And the `validators` folder contains your keystores.
+
+For more on keys in eth2, see [here](https://blog.ethereum.org/2020/05/21/keys/).
diff --git a/docs/the_nimbus_book/src/validator.md b/docs/the_nimbus_book/src/validator.md
index d3df369db..1040e5b09 100644
--- a/docs/the_nimbus_book/src/validator.md
+++ b/docs/the_nimbus_book/src/validator.md
@@ -1,7 +1,11 @@
 # Become a Validator
 
-To become a validator, you need to install the beacon chain software, acquire 32 ETH, set up your validator account, and register with the deposit contract on ethereum.
+> Note, the instructions below currently apply to Altona. They will be updated shortly to explain how you can use Nimbus to create your validator keys and interact with the Medalla deposit contract.
+>
+> To become a validator on Medalla using the [eth2 launchpad](https://medalla.launchpad.ethereum.org/), see [here](./medalla.md).
 
+
+To become a validator, you need to install the beacon chain software, acquire 32 ETH, set up your validator account, and register with the deposit contract on ethereum.
 There is currently no eth2 mainnet - all networks are testnets.
 
 ## Recommended Testnets