linking better to existing docs/tutorials

[4meta5]

GOAL: Better Integration with Docs and Other Resources

• update contribution guidelines
• fix link and random build (cherrypick from other branch)

High Demand Recipes Code (kitchen)

to point to easy examples for certain increasingly common patterns

• storage cache
• linked map
• double map
• child trie
• custom origin

after working on actual docs PR

• test scaffolding
• runtime errors

soon

• using app-specific crypto (maybe in offchain-worker context)

consider reposting each of these as questions and answers (directed to recipes) on stack overflow...ask for help from someone with stack overflow rep.

the new table of contents will look like

- [Introduction](./base/README.md)
- [Learn Rust](./base/rust.md)
- [Installation](./base/setup.md)
- [Hello Substrate](./basics/README.md)
    - [Events](./basics/events.md)
    - [Single Value Storage](./basics/value.md)
    - [Maps](./basics/maps.md)
    - [Configurable Constants](./basics/constants.md)
- [Best Practices](./design/README.md)
    - [Types and Traits](./design/ttraits.md)
    - [Economic Security](./design/econsecurity.md)
    - [Runtime Errors and Testing](./design/errtesting.md)
    - [Fixed Point Arithmetic](./design/fpamath.md)
- [Runtime Configuration](./base/runtime.md)
- [Simple Treasury](./dao/README.md)
- [Token Curated Registry](./token/README.md)
- [NFT Ticket Machine](./nft/README.md)
- [Proof of Existence](./proof/README.md)
- [Social Network](./identity/README.md)
- [Featured Tutorials](./base/dessert.md)

-----------

[More Resources](./base/resource.md)

This new structure splits the recipes into two sections separated by Runtime Configuration:

1. conceptual documentation with how-to/best practices examples/code
2. extensions of existing tutorials ie simple treasury, token curated registry, nft ticket machine, proof of existence, and social network.

(2) is designed to increase the strength of the mapping between existing resources by aligning example content with existing sample code:

• Simple Treasury: uses the previous tour/treasury with a more thorough explanation of the context behind scheduling spending and permissioned membership for governance
• Token Curated Registry: use the previous token recipe => ERC20 => TCR (update and use Gautam's tutorial)
• NFT Ticket Machine: use the most recent Cryptokitties to create a ticketing system in which purchasing a service generates a receipt which can be marked by some unique art
• Proof of Existence: use the proof of existence tutorial to look into more proof-based designs like merkle tree proofs in the runtime, child tries, etc
• Social Network: basically use DID module and/or Steve's Hyperledger Grid code

None of these are that complicated to put together because they pull heavily from existing resources.

still to do

• add Hello Substrate-esque example for introducing structure in a minimal way
• link between every recipe and the kitchen in a standardized way (maybe at the top, custom header would be nice)
• define scope in introduction (reference things not covered to existing docs)
• add intro to Rust recipe, subsume advanced optimizations in this section
• improve treasury based on feedback => open issue for comprehensive treasury overview in substrate docs => will link between the two (same pattern to followed for democracy)

maybe next PR

• configure super-runtime
• init runtime section, add simple example like joshy's loosely coupled module stuff

[shawntabrizi]

I like the direction here, but generally I feel that the structure may continue to change as it is influenced by needs of the top level documentation.

It is hard to say exactly what that will look like, but I hope we can continue to be flexible here with the structure.

I would expect it to look more like the new table of contents for development, but we shouldnt jump to this conclusion until our docs are done and actually written in this layout:

Development
-Developer Documentation
-Runtime Modules
--Overview
--Runtime Execution
--Runtime Macros
--Runtime Storage
--Runtime Events
--Runtime Errors
--Runtime Origin
--Runtime Configuration Traits
--Transaction Weight
--Runtime Tests
-Build
--Prerequisites
--Purge Chain
--Runtime Upgrades
-Front End
--Polkadot-JS
--JSON RPC

Furthermore, I hope that you are influencing your decisions with similar projects like "Rust by Example": https://doc.rust-lang.org/rust-by-example/

One this I like about it which is not explicit in your recipes, is that it starts with a "hello world" app.

For us I think it is the following:

use support::{decl_module, decl_event, decl_storage, StorageValue, StorageMap};
use system::ensure_signed;

pub trait Trait: system::Trait {
	type Event: From<Event<Self>> + Into<<Self as system::Trait>::Event>;
}

decl_event!{
	pub enum Event<T> where
		AccountId = <T as system::Trait>::AccountId,
	{
		ValueSet(AccountId, u64),
	}
}

decl_storage! {
	trait Store for Module<T: Trait> as Example {
		pub LastValue get(last_value): u64; 
		pub UserValue get(user_value): map T::AccountId => u64;
	}
}

decl_module! {
	pub struct Module<T: Trait> for enum Call where origin: T::Origin {
		fn deposit_event() = default;

		pub fn set_value(origin, value: u64) {
			let sender = ensure_signed(origin)?;
			LastValue::put(value);
			UserValue::<T>::insert(&sender, value);
			Self::deposit_event(RawEvent::ValueSet(sender, value));
		}
	}
}

[shawntabrizi]

I would also like to understand the scope of more heavy examples here.
Will users find instructions to build a social network in the recipes?

It seems like quite a huge item, and not very generic.

[4meta5]

@shawntabrizi The social network is just a catchy title for what I intended to include snippets from Steve's Hyperledger Grid example. This also fits in with internal work on DIDs, which will have APIs heavily influenced by the invocation of identity and relationships in a similar context.

I maybe have overshot for the scope, but the intent is to map the heavy examples as extensions to existing docs using useful features. This is similar to how Rust by Example show minimal examples for interesting crates/apis. Before, the context for the examples weren't clear because they didn't fit within a specific narrative that maps to our other docs. By formatting the heavy examples as minimal extensions for the existing tutorials/samples, I hope to strengthen the link between the official docs/tutorials/samples and the recipes.

I do not want the scope of recipes to extend beyond module development and runtime configuration. I cannot maintain this by myself if the scope broadens.

[shawntabrizi]

I don't think the goal is for you to maintain the recipes on your own forever, but I also dont think the goal is to extend recipes past runtime or module development either (at least in the medium term), so we should be gucci.

[JoshOrndorff]

Glad this demonstrates remove_prefix. @bkchr was asking for some docs on that.

[shawntabrizi]

Should you merge this and start opening smaller PRs for continued content creation? Or whats the plan?

[4meta5]

Should you merge this and start opening smaller PRs for continued content creation? Or whats the plan?

Definitely, I'll clean it up and merge it => split the rest into smaller PRs.