Documentation overview

[0x7CFE]

This issue contains, in no particular order, a list of entities that need to be documented either inline in the code, or in the wiki.

Many of the terms below are well known in the blockchain world. Still, it may be useful to put an emphasis on our interpretation, i.e. what is different and what are the usage contracts. Of course, we may also link to a more general description somewhere on the net, like Wikipedia or Ethereum wiki.

For example, when describing blocks and transactions we may say, that usually, blocks in classic chains contain transactions that transfer funds from one account to another. But in our case, it's not the only option. Since block internals are fully specified by the chain and not by the Substrate itself, we call them extrinsics.

I believe this list may then act as an index to the whole documentation. The thing is that just by reading through this list one should be able to get a relatively good understanding of general concepts and top-level structure of the code base.

Note: If you took an item to work on, please edit the entry for others to see. Upon completion, please put a link to the wiki page or GitHub PR where it was done.

Explain most commonly used terms in detail

• [ ] Authority
• [ ] Backend
• [ ] Block, authoring, syncing
• [ ] Byzantine Fault Tolerance (BFT)
• [x] Consensus
• [ ] ed25519
• [ ] Executor
• [x] Extrinsic (Transaction)
• [ ] Full client
• [ ] Genesis
• [ ] Gossip
• [ ] Hash
• [ ] Light client
• [ ] Nominator
• [ ] Proof of work
• [ ] Proof of stake
• [ ] Protocol (specialization)
• [x] P2P
• [ ] Runtime
• [ ] Session (PR https://github.com/paritytech/wiki/pull/271 by @ltfschoen requires review)
• [ ] Staking
• [ ] State Database
• [ ] State Transition Function (STF)
• [ ] Substrate Runtime Module Library (SRML)
• [ ] Parity Substrate Home
• [ ] Swarm
• [ ] Transaction Pool
• [ ] Trie (Merkle Tree, Patricia Tree)
• [ ] Validator
• [ ] WebAssembly (WASM)

Various entry points and concepts to be aware of

• [ ] impl_stubs!
• [x] construct_runtime! - @shawntabrizi - https://github.com/paritytech/substrate/issues/1288
• [ ] decl_apis!
• [ ] decl_module! (WIP by @0x7CFE) - @shawntabrizi - https://github.com/paritytech/substrate/issues/1288
• [ ] decl_event!
• [ ] decl_storage! - @shawntabrizi - https://github.com/paritytech/substrate/issues/1288
• [ ] impl_outer_origin!
• [ ] impl_outer_dispatch!
• [ ] impl_outer_event!
• [ ] impl_outer_inherent!
• [ ] impl_outer_config!
• [ ] impl_outer_log!
• [ ] Call (module level)
• [ ] PrivCall (module level)
• [ ] Call (dispatch level)
• [ ] PrivCall (dispatch level)
• [ ] aux

SRML modules

• [ ] example (see this first)
• [x] assets - @ltfschoen
• [x] balances
• [ ] consensus
• [ ] contract
• [x] council - @ltfschoen
• [x] democracy - @ltfschoen
• [ ] session - @ltfschoen
• [ ] staking - @ltfschoen
• [ ] timestamp
• [ ] treasury

Important types and traits

• [ ] *::Trait
• [ ] *::Service
• [ ] HasPublicAux
• [ ] bft::Environment
• [ ] bft::Proposer
• [ ] BlockBuilder
• [ ] Specialization<B>
• [ ] Encode / Decode
• [ ] Executive

Typical module structure and module roles

• [ ] api
• [ ] cli
• [ ] consensus
• [ ] executor
• [ ] network
• [ ] primitives
• [ ] runtime
• [ ] service

Various subjects that probably need to be explained

• [x] Substrate philosophy, general concepts, etc.
• [x] Overall architecture, higher level description, modules and their interaction
• [ ] Where are the entry points, how to start reading the source
• [ ] How runtime interacts with the outer code
• [ ] How to decide, what should be implemented in runtime and what not
• [ ] What parts are optional and what parts are expected to be implemented by the user
• [ ] Asynchronous model, futures, tasks, etc as it is used in the Substrate
• [ ] Life of a transaction from network to storage, how a block is imported

[chevdor]

I should be clarified where the documentation leaves, especially to help contributors contributing :) I currently see documentation in:

• the parity wiki
• the repo itself

For instance:

• https://wiki.parity.io/Extrinsic (src: https://github.com/paritytech/wiki/blob/master/Extrinsic.md)
• https://github.com/paritytech/substrate/blob/master/README.adoc#32-extrinsics

I can´t help but think that the doc should leave within the repo itself and eventually be fetched there by the Wiki. Since the repo is using Asciidoc, that allows including snippets from the code, which is better than copy pasting in .md files (ie duplicating...)

Of course, the line needs to be drawn between referencing code in an asciidoc file or providing examples as Rust allows.

Your list @0x7CFE is definitely great to see what we have and what is still missing.

[kianenigma]

@shawntabrizi have you ever seen this? Maybe we can also track doc process here?

[ltfschoen]

@Kianenigma this was where we could choose docs initiatives to work on before substrate-dev-hub became a thing

[kianenigma]

Then I suppose it should be closed if we don't intend to update it? CC @bkchr

[0zAND1z]

Limiting to asynchronous calls optionality​ from the substrate website has kept me researching on what exactly that means.

Is that WIP?

[bkchr]

I think @Kianenigma is right and we can close this.

@0zAND1z best is you ask in the Riot channel.