[main v3] Revise the published version of the private network tutorial (pre-split)

[lsgunnlsgunn]

I started down this path to simplify and streamline this one tutorial, hit a wall, but think I've found the way forward. In the process though, I started to see this tutorial as overloaded and want to split it into two parts (Simulate a network and Start a private network). I created prototypes for the split tutorials, but there might be value in having some eyes on this pre-split version if people have cycles available (the last part doesn't quite work as written and at least according to comments in the file, didn't work previously either--I think I know how to fix it, but need to test if my planned fix actually works). I'll add the split-into-two to the PoC for the doc architecture that I'm planning to build next week.

[lsgunnlsgunn]

Ready to have 👀 with a few notes:

• I want to split this into two tutorials (simulate, separate from start a private network). I did a test run in the sandbox and think it is the right way to go.
• I got everything except finalization with two nodes to work. Maybe there's a step missing?
• I'm thinking I might remove the polkadot-js "Attach a front-end" section. It doesn't add much and maybe should be a separate tutorial about connecting to a local node/connecting to a specific network.

[Eve-Parity]

Ready to have 👀 with a few notes:

• I want to split this into two tutorials (simulate, separate from start a private network). I did a test run in the sandbox and think it is the right way to go.
• I got everything except finalization with two nodes to work. Maybe there's a step missing?
• I'm thinking I might remove the polkadot-js "Attach a front-end" section. It doesn't add much and maybe should be a separate tutorial about connecting to a local node/connecting to a specific network.

I definitely agree that the tutorial needs to be split up, and instinct tells me that you're correct in how you want to split it. For me the split came right at Generate your own keys, which makes be think we're on the same page.
Agree with nixing the front-end part.

[Eve-Parity]

Suggested change

	There are several different algorithms used to reach consensus, including:
	There are several different algorithms used to reach consensus, including the following:

[Eve-Parity]

Suggested change

	* Proof of stake consensus selects the validators add valid blocks to the chain based on the cryptocurrency holdings that they have locked up as a stake in the network.
	* Proof of stake consensus selects the validators that will add valid blocks to the chain based on the cryptocurrency holdings that they have locked up as a stake in the network.

[Eve-Parity]

Should this statement be stronger, as in the machine should be air-gapped?

[lisa-parity]

@sacha-l @shawntabrizi , it would be great to have a technical review on the content (especially since I could not get finalization to work for the non-predefined accounts). I'm using the revision as the basis for splitting the tutorial into 3 parts:

1. Using predefined accounts
2. Using generated keys and a chain spec
3. Using Polkadot-JS to connect to a network or local endpoint

[sacha-l]

I gave the tutorial a full run through - a couple of things came to mind:

• The flow feels misleading: there's a lot of interesting info but I felt like I was going in different directions throughout. I think splitting it up as you suggest will fix this. The "Verify blocks are produced and finalized" seems unnecessary.
• Generating keys and keeping track of them was a pain point I encountered. For a beginner tutorial like this I feel like we should just have a section with a table of the different (aura and gran) accounts, their function and secret seeds we're using in our bash commands.
• The "Share the chain specification with others" sort of hints to what the tutorial expects me to do but it's not very clear. I think the tutorial should decide from the start whether it expects its users to ".. [create] a private blockchain network to share with other participants.." .
• The purge command seems unnecessary the first few times it's asked for (it's targeting the tmp/alice file which in theory wouldn't have been create from just completing the "Create your first Substrate blockchain" tutorial).

I was able to run the tutorial successfully btw. Just wasn't sure how to get it running with two or more separate machines.

CC: @lsgunnlsgunn

[lsgunnlsgunn]

I'm splitting this into three parts in the sandbox-removing the UI stuff from the simulated network and private network to be a standalone topic.

[lisa-parity]

I'm going to merge this as "better than the current vesion" and improve in the split up version that I have in the sandbox.

[decentration]

Hi! I'd like to make some general comments about "Start a private network" tutorial as well as tutorial workflows in general, and sorry if this not the best place, Dan Shields linked me here regarding my interest in making a how-to.

Firstly, the "Start a Private Network" has been super helpful and i still refer to it after almost a year of learning Substrate.

If I could share some comments on my achievement milestones learning Substrate, which may perhaps be helpful.

Natural learning path

For me, general achievement milestones for the DevOps side of things went something like:

1. Build a local chain produce blocks "...hurrah!"
2. Build a dev chain and connect nodes not just local "...empowering!"
3. Build a custom chain (runtime, pallets etc) "...let's dance"
   • run a chain with Docker
   • build Docker image and customize Dockerfile "praise be"
4. Build a parachain and connect it to a relay chain "...lets do dis!"
   • local
   • dev
   • produce blocks on chachacha (current task) "why won't collator blocks be produced, why why why"
5. Build a rococo staging relay testnet chain and get validators to work.
   • customise roococo staging config in chain_spec file to have 3 validators.
   • register keys. 🎶 "21 session keys hanging on the wall... and if one validator key should accidentally fall..." 🥴
   • understand about validators, aura, babe, beefy... (current task) #280

How to build a public network instead of private

A very general comment would be to drop the "private" as a main tutorial because only a small minority of beginners would be interested in building a private network, and change title to something like "How to build a test network".

Education workflows

An interesting thing could be to split various workflows into beginner, intermediate, advanced. So "How to build a private network" would be super high level for beginners, and for advanced we're learning why a lot of things are done a certain way. Easy for me to say, but would awesome.

How to build a custom relay testnet

And secondly i would like to help create one of these workflow tutorials. I was thinking the "How to build a custom relay chain testnet" would be befitting on what im working on currently. This has pushed me to learn a bit more about the validator section of things, which i request some clarity here #280 and if you could help answer any of those questions, I would be grateful.

[lisa-parity]

@decentration , thanks for the excellent feedback and suggestions. Very helpful input. I think your comment about changing the title of the tutorial is valid, but in how I'm thinking about splitting out the information, I might go in a slightly different direction. I imagine a similar progression though, moving from simple to more advanced topics--using predefined accounts, generating keys and a shared chain spec, building a small network with validator and non-validator nodes, building a full Substrate node, building a parachain, etc.