Suggestion for more backlinks to polkadot-sdk docs

[kianenigma]

Howdy, Great stuff.

Something that I am trying to establish is to help increase the depth of our tutorials by backlinking them more often to rust-docs, and generally everything else that is mentioned in polkadot-sdk-docs. This will enrich your tutorial with further foundations that help the reader learn further, should they wish to do so.

1. Initialize the pallet project

• Once we have the polkadot-sdk-frame crate not carry the experimental flag (soon, cc @gupnik), this part can be simplified. Users need not know about sp-core etc. A FRAME pallet will only have 3 deps: frame + codec/type-info.
• You can already move this to use one of the new 3 templates maintained by parity. The list is here [Templates] Systematic way to synchronize the templates in this repo and substrate-developer-hub paritytech/polkadot-sdk#3155. Similarly, @gupnik is making sure these templates are up-to-date with latest features of polkadot-sdk.
• For all the macros, link to their rust-doc. They are all filled with more contextual information about what the macro does, what are the options, and so on. Ofc, the user probably need not read this right now, but it is good for them to know where to look later. You can take this mentality to all other steps as well. Try your best to make all RystTypes, rust_function or #[rust_macros] backed by the real link to the rust-docs, all hosted from https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/index.html. And consequently, report any important type that is not well documented, and we will take care of it. Some examples for now:
  • https://paritytech.github.io/polkadot-sdk/master/frame_support/pallet_macros/attr.config.html
  • https://paritytech.github.io/polkadot-sdk/master/frame_support/pallet_macros/attr.call.html
  • https://paritytech.github.io/polkadot-sdk/master/frame_support/pallet_macros/attr.storage.html
  • https://paritytech.github.io/polkadot-sdk/master/frame_support/pallet_macros/attr.event.html
  • https://paritytech.github.io/polkadot-sdk/master/frame_support/pallet_macros/attr.error.html
• naming: prefer using polkadot-sdk and `frame' and less so 'Substrate'.
• You can probably remove 80% of the code in mock.rs by using derive_impl. Using #[frame::runtime] instead of construct_runtime! would also yield better syntax.

Is this type of feedback useful, and something that you can action upon? Would be happy to then continue reading the tutorial and provide similar comments.