Improving tutorial effectiveness

[ghost]

What
3 ideas to help with making the tutorials more effective. Some of these may apply to the rest of the docs as well.

1. Links to fiddles/potentially embedding fiddles in docs
2. Subdivision of topics into 2 categories: Theory and Application
3. Small "Check your understanding" sections at the end

I don't believe the capability to embed pawn fiddles exists as of now. In any case, links to tutorial fiddles can be helpful in providing a faster feedback loop when reading about a subject.

Check your understanding sections would be simple multiple choice/fill in the blanks questions that serve the same purpose as the fiddles. Could be done simply by putting the correct answers within a spoiler tag or by adding some functionality into the docs that would check for right answer, etc. Practically, the spoiler seems to be the winner but the built-in docs option would, in my opinion, lead to more engagement/better results.

Topics in tutorials can always, if not for the most part, be classified into those two categories. There would be no restriction for a topic to have both theory and application, but for the most part you're always applying some concept that you can link back to. Here too, I can think of two ways of supporting it:

• Simple notice at the top of each post redirecting to the other one: "This is the theoretical foundation for X. For application(s), see: [1 or more links]." and "This is an application of X. If you need to go over the concepts, see: [1 or more links].".
• Tags/groups/some way of linking one post to the other. This has the added benefit of grouping all theory posts together, and all applications together, allowing people to either do all theory first then applications, or theory-application and so on.

The first one is the easier to put in place, but the benefit of grouping these can prove useful as more tutorials are added.

Why
The better readers of a tutorial grasp the concepts at play, the better. I believe I have offered some good arguments above as to how these additions would improve the effectiveness of tutorials. I have also tried to include different ways that they could be implemented, with their advantages/disadvantages.

Curious to see your feedback on this: eager to see additions/modifications/removals, or comments.