rework substrate dev section

developer-hub/src/polkadot_sdk/frame_runtime.rs

@@ -52,7 +52,6 @@
 //! The following examples showcases a minimal pallet.
 #![doc = docify::embed!("src/polkadot_sdk/frame_runtime.rs", pallet)]
 //!
-//! ## Runtime
 //!
 //! A runtime is a collection of pallets that are amalgamated together. Each pallet typically has
 //! some configurations (exposed as a `trait Config`) that needs to be *specified* in the runtime.
@@ -71,6 +70,19 @@
 //! ## More Examples
 //!
 //! You can find more FRAME examples that revolve around specific features at [`pallet_examples`].
+//!
+//! ## Alternatives 🌈
+//!
+//! There is nothing in the Substrate's client side code-base that mandates the use of FRAME. While
+//! FRAME makes it very simple to write Substrate-based runtimes, it is by no means intended to be
+//! the only one. At the end of the day, any WASM blob that exposes the right set of runtime APIs is
+//! a valid Runtime form the point of view of a Substrate cliemt (see
+//! [`crate::reference_docs::wasm_meta_protocol`]). Notable examples are:
+//!
+//! * writing a runtime in pure Rust, as done in [this
+//!   template](https://github.com/JoshOrndorff/frameless-node-template).
+//! * writing a runtime in AssemblyScript,as explored in [this
+//!   project](https://github.com/LimeChain/subsembly).
 
 #[cfg(test)]
 mod tests {

developer-hub/src/polkadot_sdk/mod.rs

@@ -105,6 +105,13 @@
 //! - [`trie`](https://github.com/paritytech/trie)
 //! - [`parity-common`](https://github.com/paritytech/parity-common)
 //!
+//! ## Trophy Section: Notable Downstream Projects
+//!
+//! A list of projects and tools in the blockchain ecosystem that one way or another parts of the Polkadot SDK.:
+//!
+//! * [Polygon's spin-off, Avail](https://github.com/availproject/avail)
+//! * [Cardano Partner Chains](https://iohk.io/en/blog/posts/2023/11/03/partner-chains-are-coming-to-cardano/)
+//!
 //! [`substrate`]: crate::polkadot_sdk::substrate
 //! [`frame`]: crate::polkadot_sdk::frame_runtime
 //! [`cumulus`]: crate::polkadot_sdk::cumulus

developer-hub/src/polkadot_sdk/polkadot.rs

@@ -12,6 +12,10 @@
 //! - [The Polkadot Parachain Host Implementers' Guide](https://paritytech.github.io/polkadot-sdk/book/)
 //! - [Whitepaper](https://www.polkadot.network/whitepaper/)
 //!
+//! ## Alternative Clients 🌈
+//!
+//! TODO:
+//!
 //! ## Platform
 //!
 //! ### Polkadot 1.x

developer-hub/src/polkadot_sdk/substrate.rs

@@ -39,19 +39,20 @@
 //!
 //! ## How to Get Stared
 //!
-//! While most developers use [`crate::polkadot_sdk::frame_runtime`], it is worth noting a
-//! few (niche) alternatives:
+//! Substrate offers different options at the spectrum of technical freedom <-> development ease.
 //!
-//! 1. It is entirely possible to craft a substrate-based runtime without FRAME, an example of which
-//! can be found [here](https://github.com/JoshOrndorff/frameless-node-template).
-//! 2. Substrate's client side code, as mentioned above, is also highly configurable, and many teams
-//!    embark on customizing the client, for example with a custom consensus algorithm. Notable
-//!    examples of this are:
+//! * The easiest way to use Substrate is to use tap into one of the templates (some o which listed
+//!   at [`crate::polkadot_sdk::templates`]) and only tweak the parameters of the runtime or client.
+//!   This allows you to launch a blockchain in minutes, but is limited in technical freedom.
+//! * Next, most developers wish to develop their custom runtime modules, for which the de-facto way
+//! is [`frame`](crate::polkadot_sdk::frame_runtime).
+//! * Finally, Substrate is fully highly configurable at the client side as well, but this is the
+//!   most technically demanding.
 //!
-//! - <https://github.com/Cardinal-Cryptography/aleph-node>
-//! - <https://github.com/availproject/avail>
+//! > A notable Substrate-based blockchain that has built both custom FRAME pallets and custom
+//! > client-side components is <https://github.com/Cardinal-Cryptography/aleph-node>.
 //!
-//! 3. A number of Substrate-based templates are listed in [`crate::polkadot_sdk::templates`].
+#![doc = simple_mermaid::mermaid!("../../../docs/mermaid/substrate_dev.mmd")]
 //!
 //! ## Structure
 //!
@@ -128,8 +129,8 @@
 //! through which Polkadot can be utilized is by building "parachains", blockchains that are
 //! connected to Polkadot's shared security.
 //!
-//! To build a parachain, one could use [`crate::polkadot_sdk::cumulus`], the library on top
-//! of Substrate, empowering any substrate-based chain to be a Polkadot parachain.
+//! To build a parachain, one could use [`crate::polkadot_sdk::cumulus`], the library on top of
+//! Substrate, empowering any substrate-based chain to be a Polkadot parachain.
 //!
 //! ## Where To Go Next?
 //!

docs/mermaid/polkadot_sdk_parachain.mmd

@@ -7,5 +7,5 @@ flowchart LR
     FRAME -.-> ParachainRuntime
     Substrate[Substrate Client Libraries] -.-> ParachainClient
 
-    Cumulus[Cumulus Client Libraries] -.-> ParachainClient
-    Cumulus[Cumulus Runtime Libraries] -.-> ParachainRuntime
+    CumulusC[Cumulus Client Libraries] -.-> ParachainClient
+    CumulusR[Cumulus Runtime Libraries] -.-> ParachainRuntime

docs/mermaid/substrate_dev.mmd

@@ -0,0 +1,2 @@
+flowchart LR
+	T[Using a Template] --> P[Writing Your Own FRAME-Based Pallet] --> C[Custom Client]