implementers-guide: more structure for overview pages, clarify some d…

…efinitions (paritytech#1682)

roadmap/implementers-guide/src/README.md

@@ -1,5 +1,5 @@
 # Preamble
 
-This document aims to describe the purpose, functionality, and implementation of a host for Polkadot's _parachains_. It is not for the implementer of a specific parachain but rather for the implementer of the Parachain Host, which provides security and advancement for constituent parachains. In practice, this is for the implementers of Polkadot.
+This document aims to describe the purpose, functionality, and implementation of the host for Polkadot's _parachains_ functionality - that is, the software which provides security and advancement for constituent parachains. It is not for the implementer of a specific parachain but rather for the implementer of the Parachain Host. In practice, this is for the implementers of Polkadot in general.
 
 There are a number of other documents describing the research in more detail. All referenced documents will be linked here and should be read alongside this document for the best understanding of the full picture. However, this is the only document which aims to describe key aspects of Polkadot's particular instantiation of much of that research down to low-level technical details and software architecture.

roadmap/implementers-guide/src/SUMMARY.md

@@ -3,10 +3,10 @@
 [Preamble](README.md)
 
 - [Whence Parachains](whence-parachains.md)
-- [Parachains Overview](parachains-overview.md)
+- [Protocol Overview](protocol-overview.md)
+  - [Approval Process](protocol-approval.md)
 - [Architecture Overview](architecture.md)
-- [Approval Overview](approval.md)
-- [Messaging Overview](messaging.md)
+  - [Messaging Overview](messaging.md)
 - [Runtime Architecture](runtime/README.md)
   - [Initializer Module](runtime/initializer.md)
   - [Configuration Module](runtime/configuration.md)

roadmap/implementers-guide/src/architecture.md

@@ -1,6 +1,8 @@
 # Architecture Overview
 
-Our Parachain Host includes a blockchain known as the relay-chain. A blockchain is a Directed Acyclic Graph (DAG) of state transitions, where every block can be considered to be the head of a linked-list (known as a "chain" or "fork") with a cumulative state which is determined by applying the state transition of each block in turn. All paths through the DAG terminate at the Genesis Block. In fact, the blockchain is a tree, since each block can have only one parent.
+This section aims to describe, at a high level, the code architecture and subsystems involved in the implementation of an individual Parachain Host. It also illuminates certain subtleties and challenges faced in the design and implementation of those subsystems.
+
+To recap, Polkadot includes a blockchain known as the relay-chain. A blockchain is a Directed Acyclic Graph (DAG) of state transitions, where every block can be considered to be the head of a linked-list (known as a "chain" or "fork") with a cumulative state which is determined by applying the state transition of each block in turn. All paths through the DAG terminate at the Genesis Block. In fact, the blockchain is a tree, since each block can have only one parent.
 
 ```dot process
 digraph {

roadmap/implementers-guide/src/messaging.md

@@ -1,6 +1,6 @@
 # Messaging Overview
 
-Polkadot has a few mechanisms that are responsible for message passing. They can be generally divided
+The Polkadot Host has a few mechanisms that are responsible for message passing. They can be generally divided
 on two categories: Horizontal and Vertical. Horizontal Message Passing (HMP) refers to mechanisms
 that are responsible for exchanging messages between parachains. Vertical Message Passing (VMP) is
 used for communication between the relay chain and parachains.

roadmap/implementers-guide/src/approval.md → roadmap/implementers-guide/src/protocol-approval.md

@@ -1,4 +1,4 @@
-# Approval Overview
+# Approval Process
 
 The Approval Process is the mechanism by which the relay-chain ensures that only valid parablocks are finalized and that backing validators are held accountable for managing to get bad blocks included into the relay chain.
 

roadmap/implementers-guide/src/parachains-overview.md → roadmap/implementers-guide/src/protocol-overview.md

@@ -1,10 +1,10 @@
-# Parachains Overview
+# Protocol Overview
 
-This section aims to describe, at a high level, the architecture, actors, and Subsystems involved in the implementation of parachains. It also illuminates certain subtleties and challenges faced in the design and implementation of those Subsystems. Our goal is to carry a parachain block from authoring to secure inclusion, and define a process which can be carried out repeatedly and in parallel for many different parachains to extend them over time. Understanding of the high-level approach taken here is important to provide context for the proposed architecture further on.
+This section aims to describe, at a high level, the actors and protocols involved in running parachains in Polkadot. Specifically, we describe how different actors communicate with each other, what data structures they keep both individually and collectively, and the high-level purpose on why they do these things.
 
-The Parachain Host is a blockchain, known as the relay-chain, and the actors which provide security and inputs to the blockchain.
+Our top-level goal is to carry a parachain block from authoring to secure inclusion, and define a process which can be carried out repeatedly and in parallel for many different parachains to extend them over time. Understanding of the high-level approach taken here is important to provide context for the proposed architecture further on. The key parts of Polkadot relevant to this are the main Polkadot blockchain, known as the relay-chain, and the actors which provide security and inputs to this blockchain.
 
-First, it's important to go over the main actors we have involved in the parachain host.
+First, it's important to go over the main actors we have involved in this protocol.
 
 1. Validators. These nodes are responsible for validating proposed parachain blocks. They do so by checking a Proof-of-Validity (PoV) of the block and ensuring that the PoV remains available. They put financial capital down as "skin in the game" which can be slashed (destroyed) if they are proven to have misvalidated.
 1. Collators. These nodes are responsible for creating the Proofs-of-Validity that validators know how to check. Creating a PoV typically requires familiarity with the transaction format and block authoring rules of the parachain, as well as having access to the full state of the parachain.
@@ -44,7 +44,7 @@ The Approval Process, at a glance, looks like this:
 1. The secondary checkers submit the result of their checks to the relay chain. Contradictory results lead to escalation, where all validators are required to check the block. The validators on the losing side of the dispute are slashed.
 1. At the end of the Approval Process, the parablock is either Approved or it is rejected. More on the rejection process later.
 
-More information on the Approval Process can be found in the dedicated section on [Approval](approval.md).
+More information on the Approval Process can be found in the dedicated section on [Approval](protocol-approval.md).
 
 These two pipelines sum up the sequence of events necessary to extend and acquire full security on a Parablock. Note that the Inclusion Pipeline must conclude for a specific parachain before a new block can be accepted on that parachain. After inclusion, the Approval Process kicks off, and can be running for many parachain blocks at once.
 

roadmap/implementers-guide/src/runtime/scheduler.md

@@ -82,7 +82,7 @@ digraph {
 
 ## Validator Groups
 
-Validator group assignments do not need to change very quickly. The security benefits of fast rotation are redundant with the challenge mechanism in the [Approval process](../approval.md). Because of this, we only divide validators into groups at the beginning of the session and do not shuffle membership during the session. However, we do take steps to ensure that no particular validator group has dominance over a single parachain or parathread-multiplexer for an entire session to provide better guarantees of liveness.
+Validator group assignments do not need to change very quickly. The security benefits of fast rotation are redundant with the challenge mechanism in the [Approval process](../protocol-approval.md). Because of this, we only divide validators into groups at the beginning of the session and do not shuffle membership during the session. However, we do take steps to ensure that no particular validator group has dominance over a single parachain or parathread-multiplexer for an entire session to provide better guarantees of liveness.
 
 Validator groups rotate across availability cores in a round-robin fashion, with rotation occurring at fixed intervals. The i'th group will be assigned to the `(i+k)%n`'th core at any point in time, where `k` is the number of rotations that have occurred in the session, and `n` is the number of cores. This makes upcoming rotations within the same session predictable.