*THE* Polkadot SDK Tutorial

[kianenigma]

See: Polkadot-Blockchain-Academy/pba-content#592

[kianenigma]

A bonus idea that I have been thinking of is to have a clear point of split in the tutorial, where we say:

• Okay, up until this point, you could have written the whole thing using Ink! as well.
• In fact, here is the same tutorial but in Ink! cc @cmichi @athei?
• But, from now on, you cannot write this with Ink! anymore.

In essence, this will be the MERGE of the ink and FRAME tutorials to some extent.

[athei]

Yes, yes, yes. There should not be a separate master tutorial for ink! and FRAME. Having people make a decision about something they have no idea about is a sure fire way to drive them away. What I see often is people are paralyzed by the decision runtime vs smart contract. It is our fault because we just put this as one of the first things in our docs. How should they know? They just opened this website.

When coming onto the master tutorial people should never ever have to make a decision. We can just start with ink! (they think a parachain is a smart contract anyways because that is all they know) . There is no harm to just always start with ink! first because all the things you need to learn for ink! (Rust, dispatchables/messages, ...) you need for the runtime anyways. It is basically a subset of FRAME.

ink! is not a big investment when you already made the decision to get into the Polkadot ecosystem. On the other hand launching your own chain is huge and should be pitched once they are more committed or you'll scare them away. Also it shouldn't sound as this necessary to be successful as there are only so many people in the world which can and should launch a block chain. Giving the rest of the devs the message that this is the only way will drive them somewhere else. But we need them as users of the parachains that do exist. Many of those chains barely have any users. Programmability for their chains could be a great way to get users.

[hummusonrails]

I agree with @athei on this 100%.

I would add that as our docs begin to mature again, we need to think carefully about entry points into the parts of the docs for more experienced users that do know what they are specifically after. The less hunting that type of person needs to do the better. But, let's first create the master tutorial/story that seamlessly teaches how to build in Polkadot.

[kianenigma]

For the time being, I can say that I would 100% would like to write the tutorial with both Ink! and FRAME, for as much as possible. This is partially for my own understanding as well. How it will be presented, I am not sure yet.

We can either just start with Ink!, as Alex posed, or stick to FRAME, but finish each chapter with a link to "Here's how you would have done this with Ink!" or else "Here's why this is not possible anymore with Ink!".

[bkchr]

When coming onto the master tutorial people should never ever have to make a decision. We can just start with ink! (they think a parachain is a smart contract anyways because that is all they know) . There is no harm to just always start with ink! first because all the things you need to learn for ink! (Rust, dispatchables/messages, ...) you need for the runtime anyways. It is basically a subset of FRAME.

This is currently not true and also no one is working on this. We need people that write parachains. For sure there should be an explanation at the beginning highlighting clearly the differences between ink and FRAME, but then continue with the FRAME docs. Teaching people first ink and then say, hey sorry, but now you need to learn this and this new syntax, ahh and BTW there are no training wheels as with smart contracts. That is a really shitty experience. You can just look at rust, people that programmed before in C/C++ have a much easier switch to rust than people that are used to javascript. For sure it will be harder, but when you initially after the introduction decided that you want to write a parachain then let's go.

The job here is to teach parachain developers and not smart contract developers on a parachain. These parachains also have docs and can link to the ink docs to get these people onboarded to ink before they learn the special interfaces of parachain x.

[athei]

This is currently not true and also no one is working on this.

I understand. I'm merely speculating on potential areas for enhancement.

We need people that write parachains.

The job here is to teach parachain developers and not smart contract developers on a parachain.

I'd like to reconsider this notion. In my opinion, we need individuals who can leverage anything related to Polkadot in any capacity. This could range from developing a parachain (maximum engagement), deploying a smart contract (moderate engagement), to merely using a parachain (minimal engagement).

My hypothesis is as follows (and perhaps the marketing team can validate this): The group of individuals capable of maximum engagement—what we ideally seek—is minuscule compared to those who can write a smart contract. No matter how much we desire it, we can't drive them towards maximum engagement by simply avoiding discussion of other options.

Teaching people first ink and then say, hey sorry, but now you need to learn this and this new syntax, ahh and BTW there are no training wheels as with smart contracts. That is a really shitty experience.

This assumption also hinges on the belief that anyone who engages with this documentation will inevitably need to create a parachain. I am mildly concerned that the pool of individuals possessing this skill set is too limited to achieve mass adoption. If we delegate this educational responsibility to individual parachains, it could result in fragmentation of the ecosystem and dilution of our brand: Network effects are everything with a programming platform.

[bkchr]

My hypothesis is as follows (and perhaps the marketing team can validate this): The group of individuals capable of maximum engagement—what we ideally seek—is minuscule compared to those who can write a smart contract. No matter how much we desire it, we can't drive them towards maximum engagement by simply avoiding discussion of other options.

Yeah for sure. I support your hypothesis 100%. This is also the reason I said that at the beginning we should have a clear introduction to the differences between FRAME and ink. Telling people what is out there. And to take directly another point you said, "networking effects" we could then also keep the ink tutorials on this side and guide the people. However, when it comes to special chain extensions etc, we can not that much anymore as they are different per chain and require good docs by the teams. Maybe this could also at one point being integrated into one page. Who knows. Whoever, the entire thing @kianenigma is doing is to ensure that we have good tutorials/docs for FRAME right now. We can not tackle all the things at once, we need to focus and the focus here is FRAME with a really good introduction FRAME vs ink, when to use what and then link out to the current ink tutorials.

This assumption also hinges on the belief that anyone who engages with this documentation will inevitably need to create a parachain. I am mildly concerned that the pool of individuals possessing this skill set is too limited to achieve mass adoption. If we delegate this educational responsibility to individual parachains, it could result in fragmentation of the ecosystem and dilution of our brand: Network effects are everything with a programming platform.

I would like to raise a bold hypothesis, mass adoption will not come from any single parachain/contract. Mass adoption will come with a simple UX and a dead simple use case in form of a Dapp that connects multiple of these things.

I really hope that ink will shift its focus to be more of a Polkadot focused smart contract language than trying to copy solidity. We need to show off what you can do as cool shit on Polkadot with ink and not provide ABI compatibility for ETH tooling etc. When you can convince people that they can write simple on-demand parachains with ink it will be a much bigger selling point IMO then implementing legacy software interfaces.

[sacha-l]

My view is that there's already only a small portion of web3 devs in the world. Most of them know smart contracts. Out of that portion, a tiny tiny fraction are interested in building their own blockchains. The subset of smart contract devs are also an audience who will create network effects (i.e. people from outside communities talk). In my opinion, the tutorial should be structured to lure in smart contract devs and ease them into learning about FRAME and writing their own chains that can use both ink! and custom pallets.

My suggestion would be to make it a prerequisite to complete a simple ink! tutorial (e.g. a build a voting dapp). Then this "master" tutorial's starting point is to re-create the same logic as a pallet. And as it progresses, to teach about the richer capabilities you get from writing pallets. And then bring in hands-on examples of doing hybrid contract-to-pallet interactions.

Throughout, it should comfort the user about the parallels they could be drawing from the smart contract world they're mostly familiar with. The learning value would still hold even for people that already know FRAME, because if this master tutorial is successful it would teach building pallets in the context of how they can be used alongside ink! smart contracts.

[bkchr]

Throughout, it should comfort the user about the parallels they could be drawing from the smart contract world they're mostly familiar with.

Picking up people by giving them comparisons to what they know from the smart contract world and why that maybe doesn't work in the FRAME world sounds like a good idea!

The learning value would still hold even for people that already know FRAME, because if this master tutorial is successful it would teach building pallets in the context of how they can be used alongside ink! smart contracts.

Yeah for sure that can come at some later point in the tutorials. However, we should not forget about all the things in between that you first need to learn that are more important.

My suggestion would be to make it a prerequisite to complete a simple ink! tutorial (e.g. a build a voting dapp). Then this "master" tutorial's starting point is to re-create the same logic as a pallet. And as it progresses, to teach about the richer capabilities you get from writing pallets. And then bring in hands-on examples of doing hybrid contract-to-pallet interactions.

Not sure I would put that as a prerequisite, but more like a possible starting point.

The point here being you are talking all the time about the deep connection between ink and FRAME, which isn't really existing right now. There is also no default mode that each FRAME runtime has pallet contracts. I'm not against teaching these things, but we should also not let it look like there is such a deep/hard required connection.

[CrackTheCode016]

I'm jumping in on this as I'm working on a relevant PR: w3f/polkadot-wiki#4810.

It aims to answer the question: When a developer "stumbles", or hears of Polkadot, what should they learn? Where should they be "pointed" to?

My initial answer is to solidify Polkadot's context, and that goes back to explaining Substrate and FRAME first. This is supported because Polkadot presents itself as a place to create block space that caters to your specific use case, which is what Substrate (and subsequently Cumulus).

A recent call with an educational institute showed confusion about the choice for what. Namely, how does Polkadot relate to Substrate, Cumulus, FRAME, and pallets? Funnily enough, they are using Polkadot as the "step above" learning how to build EVM contracts.

This is also the reason I said that at the beginning, we should have a clear introduction to the differences between FRAME and ink.

This really should do it. Offering a couple of "tracks" wouldn't be a bad idea either, where one master guide teaches more architectural design with FRAME and the other more a way to utilize ink! for a dApp. These tracks could converge at a point to further, for example, show how something like pallet-contracts was designed and implemented and what decisions led it to that point.

I also view ink! and FRAME as two separate things; they really are. Ultimately, learning to write a pallet from scratch with the correct guidance and "dos and don'ts", and values could be pretty valuable in showcasing true considerations of blockchain engineering outside of the typical sandboxed contract environment.

IMHO, merely presenting contracts as the first option of development is underselling the potential of Polkadot. Pallet development itself isn't even particularly hard, it's making the right decisions that utilize block space in the most optimal that's more crucial to emphasize.

My suggestion as an end goal would be to produce not just a guide, but delving slightly into thoughtful consideration and implications of designing a blockchain.