diff --git a/substrate/core/client/db/README.adoc b/substrate/core/client/db/README.adoc
new file mode 100644
index 0000000000..c0b123392c
--- /dev/null
+++ b/substrate/core/client/db/README.adoc
@@ -0,0 +1,13 @@
+
+= Client DB
+
+.Summary
+[source, toml]
+----
+include::Cargo.toml[lines=2..5]
+----
+
+.Description
+----
+include::src/lib.rs[tag=description]
+----
diff --git a/substrate/core/client/src/lib.rs b/substrate/core/client/src/lib.rs
index 9526091dad..43a4be7a80 100644
--- a/substrate/core/client/src/lib.rs
+++ b/substrate/core/client/src/lib.rs
@@ -14,7 +14,9 @@
 // You should have received a copy of the GNU General Public License
 // along with Substrate.  If not, see <http://www.gnu.org/licenses/>.
 
+// tag::description[]
 //! Substrate Client and associated logic.
+// end::description[]
 
 #![warn(missing_docs)]
 #![recursion_limit="128"]
diff --git a/substrate/core/consensus/common/README.adoc b/substrate/core/consensus/common/README.adoc
new file mode 100644
index 0000000000..d8f9e1daf2
--- /dev/null
+++ b/substrate/core/consensus/common/README.adoc
@@ -0,0 +1,12 @@
+= Consensus Common
+
+.Summary
+[source, toml]
+----
+include::Cargo.toml[lines=2..5]
+----
+
+.Description
+----
+include::src/lib.rs[tag=description]
+----
diff --git a/substrate/core/consensus/common/src/lib.rs b/substrate/core/consensus/common/src/lib.rs
index a5bf6d218a..fde9d20ec9 100644
--- a/substrate/core/consensus/common/src/lib.rs
+++ b/substrate/core/consensus/common/src/lib.rs
@@ -14,7 +14,10 @@
 // You should have received a copy of the GNU General Public License
 // along with Substrate Consensus Common.  If not, see <http://www.gnu.org/licenses/>.
 
+// tag::description[]
 //! Tracks offline validators.
+// end::description[]
+
 #![allow(dead_code)]
 
 #![cfg(feature="rhd")]
diff --git a/substrate/core/consensus/rhd/README.adoc b/substrate/core/consensus/rhd/README.adoc
new file mode 100644
index 0000000000..ff7bde1714
--- /dev/null
+++ b/substrate/core/consensus/rhd/README.adoc
@@ -0,0 +1,12 @@
+= Consensus Rhododendron (RHD)
+
+.Summary
+[source, toml]
+----
+include::Cargo.toml[lines=2..5]
+----
+
+.Description
+----
+include::src/lib.rs[tag=description]
+----
diff --git a/substrate/core/consensus/rhd/src/lib.rs b/substrate/core/consensus/rhd/src/lib.rs
index 4edc8fc893..0bb0cbc3c6 100644
--- a/substrate/core/consensus/rhd/src/lib.rs
+++ b/substrate/core/consensus/rhd/src/lib.rs
@@ -14,6 +14,7 @@
 // You should have received a copy of the GNU General Public License
 // along with Substrate.  If not, see <http://www.gnu.org/licenses/>.
 
+// tag::description[]
 //! BFT Agreement based on a rotating proposer in different rounds.
 //!
 //! Where this crate refers to input stream, should never logically conclude.
@@ -29,6 +30,7 @@
 //! conclude without having witnessed the conclusion.
 //! In general, this future should be pre-empted by the import of a justification
 //! set for this block height.
+// end::description[]
 
 #![cfg(feature = "rhd")]
 
diff --git a/substrate/core/executor/src/lib.rs b/substrate/core/executor/src/lib.rs
index df67db587f..64442b7f8e 100644
--- a/substrate/core/executor/src/lib.rs
+++ b/substrate/core/executor/src/lib.rs
@@ -24,7 +24,7 @@
 //! - execute_block(bytes)
 //! - init_block(PrevBlock?) -> InProgressBlock
 //! - add_transaction(InProgressBlock) -> InProgressBlock
-//! I leave it as is for now as it might be removed before this is ever done.
+//! It is left as is for now as it might be removed before this is ever done.
 // end::description[]
 
 #![warn(missing_docs)]
diff --git a/substrate/core/finality-grandpa/README.adoc b/substrate/core/finality-grandpa/README.adoc
new file mode 100644
index 0000000000..5338cf9e8c
--- /dev/null
+++ b/substrate/core/finality-grandpa/README.adoc
@@ -0,0 +1,12 @@
+= Finality GRANDPA (aka SHAFT)
+
+.Summary
+[source, toml]
+----
+include::Cargo.toml[lines=2..5]
+----
+
+.Description
+----
+include::src/lib.rs[tag=description]
+----
diff --git a/substrate/core/finality-grandpa/src/lib.rs b/substrate/core/finality-grandpa/src/lib.rs
index 969ebc197a..76fb1761bd 100644
--- a/substrate/core/finality-grandpa/src/lib.rs
+++ b/substrate/core/finality-grandpa/src/lib.rs
@@ -14,9 +14,11 @@
 // You should have received a copy of the GNU General Public License
 // along with Substrate.  If not, see <http://www.gnu.org/licenses/>.
 
+// tag::description[]
 //! Integration of the GRANDPA finality gadget into substrate.
 //!
 //! This is a long-running future that produces finality notifications.
+// end::description[]
 
 extern crate finality_grandpa as grandpa;
 extern crate futures;
diff --git a/substrate/core/keyring/src/lib.rs b/substrate/core/keyring/src/lib.rs
index 3fab7c5769..6ba79d146c 100644
--- a/substrate/core/keyring/src/lib.rs
+++ b/substrate/core/keyring/src/lib.rs
@@ -15,7 +15,7 @@
 // along with Substrate.  If not, see <http://www.gnu.org/licenses/>.
 
 // tag::description[]
-//! Support code for the runtime.
+//! Support code for the runtime. A set of test accounts.
 // end::description[]
 
 #[macro_use] extern crate hex_literal;
diff --git a/substrate/core/service/src/lib.rs b/substrate/core/service/src/lib.rs
index 848c96ae90..2acc8d7661 100644
--- a/substrate/core/service/src/lib.rs
+++ b/substrate/core/service/src/lib.rs
@@ -15,7 +15,7 @@
 // along with Substrate.  If not, see <http://www.gnu.org/licenses/>.
 
 // tag::description[]
-//! Substrate service. Starts a thread that spins the network, the client and the extrinsic pool.
+//! Substrate service. Starts a thread that spins up the network, client, and extrinsic pool.
 //! Manages communication between them.
 // end::description[]
 
diff --git a/substrate/core/sr-api/README.adoc b/substrate/core/sr-api/README.adoc
new file mode 100644
index 0000000000..debd87e8eb
--- /dev/null
+++ b/substrate/core/sr-api/README.adoc
@@ -0,0 +1,12 @@
+= Runtime API
+
+.Summary
+[source, toml]
+----
+include::Cargo.toml[lines=2..5]
+----
+
+.Description
+----
+include::src/lib.rs[tag=description]
+----
diff --git a/substrate/core/sr-api/src/lib.rs b/substrate/core/sr-api/src/lib.rs
index b610606d02..0ddc89b14e 100644
--- a/substrate/core/sr-api/src/lib.rs
+++ b/substrate/core/sr-api/src/lib.rs
@@ -14,7 +14,9 @@
 // You should have received a copy of the GNU General Public License
 // along with Substrate.  If not, see <http://www.gnu.org/licenses/>.
 
+// tag::description[]
 //! API's for interfacing with the runtime via native/wasm.
+// end::description[]
 
 #![cfg_attr(not(feature = "std"), no_std)]
 
diff --git a/substrate/core/sr-primitives/README.adoc b/substrate/core/sr-primitives/README.adoc
new file mode 100644
index 0000000000..0e9d636111
--- /dev/null
+++ b/substrate/core/sr-primitives/README.adoc
@@ -0,0 +1,12 @@
+= Runtime Primitives
+
+.Summary
+[source, toml]
+----
+include::Cargo.toml[lines=2..5]
+----
+
+.Description
+----
+include::src/lib.rs[tag=description]
+----
diff --git a/substrate/core/sr-primitives/src/lib.rs b/substrate/core/sr-primitives/src/lib.rs
index 15b86484a6..36f5cda207 100644
--- a/substrate/core/sr-primitives/src/lib.rs
+++ b/substrate/core/sr-primitives/src/lib.rs
@@ -14,8 +14,10 @@
 // You should have received a copy of the GNU General Public License
 // along with Substrate.  If not, see <http://www.gnu.org/licenses/>.
 
+// tag::description[]
 //! System manager: Handles all of the top-level stuff; executing block/transaction, setting code
 //! and depositing logs.
+// end::description[]
 
 #![cfg_attr(not(feature = "std"), no_std)]
 
diff --git a/substrate/core/sr-sandbox/src/lib.rs b/substrate/core/sr-sandbox/src/lib.rs
index 7b6dc67feb..6ed3243dc8 100755
--- a/substrate/core/sr-sandbox/src/lib.rs
+++ b/substrate/core/sr-sandbox/src/lib.rs
@@ -15,25 +15,25 @@
 // along with Substrate.  If not, see <http://www.gnu.org/licenses/>.
 
 // tag::description[]
-//! This crate provides means of instantiation and execution of wasm modules.
+//! This crate provides means to instantiate and execute wasm modules.
 //!
-//! It works even when the user of this library is itself executes
-//! inside the wasm VM. In this case same VM is used for execution
+//! It works even when the user of this library executes from
+//! inside the wasm VM. In this case the same VM is used for execution
 //! of both the sandbox owner and the sandboxed module, without compromising security
-//! and without performance penalty of full wasm emulation inside wasm.
+//! and without the performance penalty of full wasm emulation inside wasm.
 //!
-//! This is achieved by using bindings to wasm VM which are published by the host API.
-//! This API is thin and consists of only handful functions. It contains functions for instantiating
-//! modules and executing them and for example doesn't contain functions for inspecting the module
-//! structure. The user of this library is supposed to read wasm module by it's own means.
+//! This is achieved by using bindings to the wasm VM, which are published by the host API.
+//! This API is thin and consists of only a handful functions. It contains functions for instantiating
+//! modules and executing them, but doesn't contain functions for inspecting the module
+//! structure. The user of this library is supposed to read the wasm module.
 //!
-//! When this crate is used in `std` environment all these functions are implemented by directly
-//! calling wasm VM.
+//! When this crate is used in the `std` environment all these functions are implemented by directly
+//! calling the wasm VM.
 //!
-//! Example of possible use-cases for this library are following:
+//! Example of possible use-cases for this library are the following:
 //!
-//! - implementing smart-contract runtimes which uses wasm for contract code
-//! - executing wasm substrate runtime inside of a wasm parachain
+//! - implementing smart-contract runtimes that use wasm for contract code
+//! - executing a wasm substrate runtime inside of a wasm parachain
 //! - etc
 // end::description[]
 
diff --git a/substrate/core/sr-version/README.adoc b/substrate/core/sr-version/README.adoc
new file mode 100644
index 0000000000..28db6c615d
--- /dev/null
+++ b/substrate/core/sr-version/README.adoc
@@ -0,0 +1,13 @@
+
+= Runtime Version
+
+.Summary
+[source, toml]
+----
+include::Cargo.toml[lines=2..5]
+----
+
+.Description
+----
+include::src/lib.rs[tag=description]
+----
diff --git a/substrate/core/sr-version/src/lib.rs b/substrate/core/sr-version/src/lib.rs
index 8af084da5e..6f91692b82 100644
--- a/substrate/core/sr-version/src/lib.rs
+++ b/substrate/core/sr-version/src/lib.rs
@@ -14,7 +14,9 @@
 // You should have received a copy of the GNU General Public License
 // along with Substrate.  If not, see <http://www.gnu.org/licenses/>.
 
-//! Version module for runtime; Provide a function that returns runtime version.
+// tag::description[]
+//! Version module for the Substrate runtime; Provides a function that returns the runtime version.
+// end::description[]
 
 #![cfg_attr(not(feature = "std"), no_std)]
 
diff --git a/substrate/core/telemetry/src/lib.rs b/substrate/core/telemetry/src/lib.rs
index 729f6f76d9..aa7479cc82 100644
--- a/substrate/core/telemetry/src/lib.rs
+++ b/substrate/core/telemetry/src/lib.rs
@@ -17,7 +17,7 @@
 // tag::description[]
 //! Telemetry utils.
 //!
-//! `telemetry` macro be used from whereever in the Substrate codebase
+//! `telemetry` macro may be used anywhere in the Substrate codebase
 //! in order to send real-time logging information to the telemetry
 //! server (if there is one). We use the async drain adapter of `slog`
 //! so that the logging thread doesn't get held up at all.
diff --git a/substrate/core/transaction-pool/README.adoc b/substrate/core/transaction-pool/README.adoc
new file mode 100644
index 0000000000..336a67a841
--- /dev/null
+++ b/substrate/core/transaction-pool/README.adoc
@@ -0,0 +1,13 @@
+
+= Transaction Pool
+
+.Summary
+[source, toml]
+----
+include::Cargo.toml[lines=2..5]
+----
+
+.Description
+----
+include::src/lib.rs[tag=description]
+----
diff --git a/substrate/core/trie/README.adoc b/substrate/core/trie/README.adoc
new file mode 100644
index 0000000000..953724ca12
--- /dev/null
+++ b/substrate/core/trie/README.adoc
@@ -0,0 +1,12 @@
+= Substrate Trie
+
+.Summary
+[source, toml]
+----
+include::Cargo.toml[lines=2..5]
+----
+
+.Description
+----
+include::src/lib.rs[tag=description]
+----
diff --git a/substrate/core/trie/README.md b/substrate/core/trie/README.md
deleted file mode 100644
index 57d392057b..0000000000
--- a/substrate/core/trie/README.md
+++ /dev/null
@@ -1 +0,0 @@
-This crate provides utility functions to interact with Substrate's Modified Merkle Patricia tree ("trie").
\ No newline at end of file
diff --git a/substrate/core/trie/src/lib.rs b/substrate/core/trie/src/lib.rs
index 87d955a357..68dacf2668 100644
--- a/substrate/core/trie/src/lib.rs
+++ b/substrate/core/trie/src/lib.rs
@@ -14,7 +14,9 @@
 // You should have received a copy of the GNU General Public License
 // along with Parity.  If not, see <http://www.gnu.org/licenses/>.
 
-//! Substrate-format Base-16 Modified Merkle Patricia Tree (Trie).
+// tag::description[]
+//! Utility functions to interact with Substrate's Base-16 Modified Merkle Patricia tree ("trie").
+// end::description[]
 
 // TODO: no_std
 
diff --git a/substrate/doc/packages/misc.adoc b/substrate/doc/packages/misc.adoc
index 316cf44858..2081d34efc 100644
--- a/substrate/doc/packages/misc.adoc
+++ b/substrate/doc/packages/misc.adoc
@@ -3,8 +3,6 @@
 
 :leveloffset: +3
 
-include::../../safe-mix/README.adoc[]
-
 include::../../subkey/README.adoc[]
 
 :leveloffset: -3
diff --git a/substrate/doc/packages/substrate.adoc b/substrate/doc/packages/substrate.adoc
index ee246d0909..3df3366def 100644
--- a/substrate/doc/packages/substrate.adoc
+++ b/substrate/doc/packages/substrate.adoc
@@ -1,62 +1,66 @@
 
 == Substrate Packages
 
+=== Substrate Core
+
 :leveloffset: +3
 
-include::../../core/bft/README.adoc[]
-
-include::../../core/cli/README.adoc[]
-
 include::../../core/client/README.adoc[]
 
-include::../../codec/README.adoc[]
+include::../../core/test-client/README.adoc[]
 
-include::../../environmental/README.adoc[]
+include::../../core/client/db/README.adoc[]
+
+include::../../core/state-db/README.adoc[]
+
+include::../../core/consensus/common/README.adoc[]
+
+include::../../core/consensus/rhd/README.adoc[]
 
 include::../../core/executor/README.adoc[]
 
+include::../../core/finality-grandpa/README.adoc[]
+
 include::../../core/transaction-pool/README.adoc[]
 
 include::../../core/keyring/README.adoc[]
 
-include::../../core/keystore/README.adoc[]
-
-include::../../core/misbehavior-check/README.adoc[]
-
 include::../../core/network/README.adoc[]
 
 include::../../core/network-libp2p/README.adoc[]
 
-include::../../core/primitives/README.adoc[]
-
-include::../../pwasm-alloc/README.adoc[]
-
 include::../../core/rpc/README.adoc[]
 
 include::../../core/rpc-servers/README.adoc[]
 
 include::../../srml/README.adoc[]
 
+include::../../core/sr-api/README.adoc[]
+
 include::../../core/sr-io/README.adoc[]
 
+include::../../core/sr-primitives/README.adoc[]
+
 include::../../core/sr-sandbox/README.adoc[]
 
 include::../../core/sr-std/README.adoc[]
 
-include::../../core/runtime-support/README.adoc[]
-
-include::../../core/serializer/README.adoc[]
-
-include::../../core/service/README.adoc[]
-
-include::../../core/state-db/README.adoc[]
-
 include::../../core/state-machine/README.adoc[]
 
+include::../../core/test-runtime/README.adoc[]
+
 include::../../core/telemetry/README.adoc[]
 
-include::../../core/test-client/README.adoc[]
+include::../../core/cli/README.adoc[]
 
-include::../../core/test-srml/README.adoc[]
+include::../../core/service/README.adoc[]
+
+include::../../core/trie/README.adoc[]
+
+include::../../core/keystore/README.adoc[]
+
+include::../../core/primitives/README.adoc[]
+
+include::../../core/serializer/README.adoc[]
 
 :leveloffset: -3