Tracking Issue for Reference Docs

[kianenigma]

Reference docs are topics that are too high level to be explained in a rust-doc, and too low level to be explained in a high level tutorial. The goal is to minimize this category.

FRAME, Substrate

• When should you write a pallet and when should you write a contract.
• System accounts; consumers and providers.
• Currency related traits, old ones (Currency, ReservableCurrency etc.) and new ones (fungible::*).
• All the ways to log and print in the runtime. The final answer to: https://stackoverflow.com/questions/57109715/how-to-print-out-tracing-message-in-substrate-runtime-development
  • https://polkadot-blockchain-academy.github.io/pba-book/substrate/tips-tricks/page.html#logging-and-prints-in-the-runtime
• Composite enums. Runtime enums and normal ones.
• origin, account abstraction
• lose coupling vs. tight coupling of pallets.
• Weight and benchmarking.
• How to configure block times: paritytech/polkadot-sdk#483
• How you create a substrate based extrinsic from scratch using just SCALE @josepot (UncheckedExtrinsic)
• cross chain asset transfer one-stop shop: paritytech/polkadot-sdk#107
• outcomes of https://forum.parity.io/t/chatgpt-powered-data-wizardry-to-understand-substrates-biggest-pain-points-using-stackexchange-data/1869
• Defensive programming.
• Chain-Spec: what it is, what it does, how to use it, etc: #20 (comment), and genesis builder @MichalGawronskiKot
• CLI: #17
• All the ways in which you can blow up either stack or heap in runtime. Box, and being memory conscious.
• Signed Extensions
• Offchain workers, and how they are not a magic silver bullet
  • https://forum.polkadot.network/t/offchain-workers-design-assumptions-vulnerabilities/2548

Pretty much every lecture in PBA is a candidate.

Misc

• Substrate Architecture; WASM Meta-protocol; Runtime
• Ultimate testing tools index: https://forum.polkadot.network/t/test-frameworks-and-utilities-for-polkadot-and-friends/2612
• How to navigate rust-docs + answer common questions using them.

Subtasks

Beta Give feedback

1. Cover most popular pages in docs.substrate.io #34
   L1-ref-docs +1
   
2. Ref doc list #39
   11 of 23
   L1-ref-docs +1

[kianenigma]

A few guidelines about writing reference docs:

1. They will be standalone crates in the mono-repo, in a location that is yet to be decided (probably in paritytech/polkadot-sdk#1477)
2. These crates will contain no meaningful code. The only reason for them to have code snippets is to be able to showcase them in the rendered rust-doc with docify. See paritytech/polkadot-sdk#991.
3. These crates will bring in dependencies such that they can docify types and traits from their dependencies. For example, it should be pretty common to pull in sp-runtime and frame-support such that you can docify and grab a trait form a path in these crates and show it in your docs.
4. While writing reference docs, consider the following:
   • If the concept you are documenting can be explained in rust-docs, just do it there.
   • Consequently, keep reference docs at minimum length. They will be a maintenance burden. The fewer lines of text, the better.
   • In other words, heavily rely on the principle of ground-up, Less-is-more and DRY.
5. Once done, please identify which pages of substrate.io are covering the same topic. Make a PR to https://github.com/substrate-developer-hub/substrate-docs/ which adds a banner to these pages that clearly says "the content of this page might have been deprecated by now, and the latest version is ". @wentelteefje and I can help with providing a template for this.