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: https://github.com/paritytech/polkadot-sdk/issues/483
• [x] How you create a substrate based extrinsic from scratch using just SCALE @josepot (UncheckedExtrinsic)
• [ ] cross chain asset transfer one-stop shop: https://github.com/paritytech/polkadot-sdk/issues/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: https://github.com/paritytech/polkadot-sdk-docs/issues/20#issue-1816702727, and genesis builder @MichalGawronskiKot
• [ ] CLI: https://github.com/paritytech/polkadot-sdk-docs/issues/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

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

### Subtasks
- [ ] https://github.com/paritytech/polkadot-sdk-docs/issues/34
- [ ] https://github.com/paritytech/polkadot-sdk-docs/issues/39

[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 https://github.com/paritytech/polkadot-sdk/pull/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 https://github.com/paritytech/polkadot-sdk/issues/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.