Define guided tutorial structure and schema

[sideninja]

Describe the feature few words

We need to define file structure for guided tutorials as well as content formatting. This way front end will be able to use that content and show guided tutorials UI.

What will be the end result of this change?

Content for guided tutorials according to the format. We should provide one such example for others to reference.

Is there any previous work that needs to be completed before making this change?

No.

Which components will this change affect?

The frontend will need to implement this format.

[sideninja]

Lets first start with Hello World tutorial

[sideninja]

https://wiki.ubc.ca/Documentation:Mini-Lessons_Basics_-_BOPPPS_Model_for_Planning_Lessons

[sideninja]

@alilloig any updates on this?

[joshuahannan]

I would imagine that the files would be the same as they are currently, right?

[sideninja]

I would keep the current structure of contracts, scripts, transactions. The one thing I would add is doc files separated into steps accompanied by a test script file that would tell us if the step was completed or not.

[joshuahannan]

I don't have any context on this, so I'm not sure what this is actually accomplishing. The code for the tutorials is stored here: https://github.com/onflow/flow-playground-tutorials
and we've been just using a regular saved playground session via a shared link to provide a starting state for each tutorial.
I think it would be ideal for the playground to load the files from that (or another repo) directly so we can stop worrying about copying and saving playground links because that is no fun. Is that what this task is meant to accomplish or is it different than that?

[sideninja]

Hey, yeah our goal is to pull the files directly from that repo. But that means the repo will have to follow some structure (and I feel the established structure of having contracts, scripts, transactions will do). But since this tutorials will become guided tutorials which means a tutorial will be broken into multiple steps and each step will have a check (I'm thinking a script testing the action was actually done). You can check the guided tutorial UI in the figma for you to have a better sense of what we are trying to do. Also the content of each tutorial will then somehow be broken in those steps. So we have to agree how we will denote that in the content or structure (steps into multiple markdown files or with certain titles or any other ideas). Do you have some input?

[joshuahannan]

You can check the guided tutorial UI in the figma

Where do I find this?

I think keeping it in the established structure is good, but it is still unclear to me what other structure there needs to be. Are you saying that we'd break up the existing tutorial into multiple markdown files that are shown between each code step that the user takes? That seems fine to me if that is the case, but I'll defer to y'all. Y'all can break it up however you want, but I'd want to be consulted first if you're planning on changing the actual content of the explanations and such in the tutorials

[sideninja]

we'd break up the existing tutorial into multiple markdown files that are shown between each code step that the user takes?

Yes, either multiple md files or maybe define the steps by title ("H1/H2.." level). The folder structure should stay as it is. But how about adding the test scripts validating each step? should that be part of the tests folder? I don't want to put that in the "scripts" folder as the scripts will all be showed as part of the tutorial script files then.

[joshuahannan]

Those can probably just be in the scripts folder because they might be useful for the user to run on their own as well as the tutorial running it in the background

[sideninja]

@joshuahannan the problem is that then we have to do some additional logic to not show those in the FE of playground. I feel we should define where tests will live as part of this standards, especially now with Cadence adding support for tests it would be wise to add that to the current standard/structure. I feel there are two ways to do this, one is to have a test folder where all tests live the other is to have test along with things they are testing (those are two established patterns I've seen in web2 development) but named with a prefix like test_. I don't mind either but I feel it's important we define this. What are your thoughts?

[joshuahannan]

I'm saying that they should be visible in the FE of the playground. A user might want to see what is being run to verify their state is correct and run it themselves.

[sideninja]

No, we don't want that.

[joshuahannan]

No, we don't want that.

Can you elaborate a bit? I usually like giving the user more flexibility to explore and try stuff out if they're learning

As for where to put Cadence tests, I'm in favor of having them in separate directories

[sideninja]

Of course, sorry. A product decision was made not to expose that, as far as my opinion goes, I agree, and the reason behind that is that purpose of the playground is to onboard new developers and make their learning curve as easy as possible. Exposing how we test whether a certain test passes for them to proceed with the tutorial will expose the mechanics behind guided tutorials and expose more scripts they need to understand why are there in the first place. If you take a look in the designs here you will see we have abstracted the process of detecting completion of each step for the purpose of hiding complexity. I normally would agree to show users as much as possible, but in the case of making onboarding as easy as possible, it's not probably the best. cc @srinjoyc if you want to elaborate further.

[joshuahannan]

Thanks for sharing! 😄 That makes sense to me.

[sideninja]

👍 we could however optionally expose that if the user decides to do that. But that is then also a bit out of the scope of this initial work.