Tutorial repository

[erickzanardo]

I would like to start a discussion about having our own official tutorials. I think that the state that our release candidates are now, it is safe to start writing the tutorials if we continuously update it as we release new versions.

I will start with what I thought on a structure, we can discuss on top of it, or if anyone has any other structure proposal this discussion is the place to share it.

My proposal: A flame_tutorials repository.

This repository would be a mono repository, with a structure somehow similar to what we have now on doc/examples on Flame repository, meaning that we would have a bunch of flutter applications with their platform folders omitted. We could organize the file structure as the following: On the root we would have the README file where it would contain some general instructions, like explaining how to use the repository, how to run the examples, and an index of all the tutorials contained there. Which tutorial would be on its own folder and it can have many steps folder, it would have a README on the root folder which would be pretty much like the README of the project, but on this case with information about that particular tutorial and an index for the steps of that tutorial.

That would look like something like this:

 |- README.md
 |-tutorials/
   |- basic/
     |- README.md
     |- step1/
       |- README.md
       |- code/
         |-  ...
     |- step2/
       |- README.md
       |- code/
         |-  ...
   |- sprites/
     |- README.md
     |- step1/
       |- README.md
       |- code/
         |-  ...
     |- step2/
       |- README.md
       |- code/
         |-  ...

What do you think?

[spydon]

Awesome! Would be nice if it automagically deployed with running examples too.

[erickzanardo]

Yes, initially, I think people could browser directly on github as github shows markdowns quite nice already, but we could think on all sort of automations afterwards as step 2, 3, etc

[spydon]

True, we should start small.
Hah, have they added some Stackoverflow like voting on the discussions now?

[wolfenrain]

I think we should opt to use a static site generator and follow the article structure that it uses. That way we can easily add theming and write our tutorials as proper articles and easily namespace them, categories them.

One example that I want to give is my own blog, it uses Hugo to generate the site and I can just write markdown. I even added a way to easily use existing example codes within my articles:

As you can see here you have a bit of text and some code, and that code references a source. If we look at my markdown you see that there is not a single line of code there, instead it reads from a file with the given line numbers:

You are probably wondering what a pool or strategy is, well simply put a pool is the data structure for all the bodies and is used to pull and store bodies efficiently. And the strategy is what Box2D will use for collision detection, the exact details about them are also unknown for me but in most cases you can just skip the last three ways of construction and just use the `World.withGravity`:
{{% code file="/examples/worlds/lib/main.dart" lang="dart" from=8 to=10 %}}

This allows us to easily write example code and articles without having the markdown be filled up with the all the code that we also want to have "runnable" so you only have to write the code once.

If you are interested in how it all works, my blog is fully opensource: https://gitlab.com/wolfenrain/blog/. Let me know what you guys think of this.

[erickzanardo]

I think your idea could be complementary. Like, I agree that we should use some template engine to avoid the need to replicate code on tutorial, but I don't think we should use a static site generator already available, but to eventually write our own generator for this repository. Because it would be very cool if we could also, have the examples running live on the site as well.

[wolfenrain]

That is still possible to do, a static site generator, generates html.. And most of them allow you to add custom pages as well so each example can be "generated" by us to be a page where you can see it live.

But there is a difference between a tutorial and an example, as @luanpotter said there might be an overlap. So I think we also have to define when something is a tutorial, and when something is an example. Because a tutorial in my opinion is "An explanation/guide of a certain type of game, or a game technique" and examples would be "How does functionality A or functionality B of the Flame-engine work"

[luanpotter]

I wonder how much overlap this would have with flame_examples, but I can see the value in keeping both separate.

[erickzanardo]

Maybe some, but on the tutorials, the most important thing is the guide, which is something that we don't have on flame_examples, and on flame_examples, when we start to improve the examples, adding modifiable properties and etc, the code that we will see here, will be much different from the codes that we see there.