bevyengine / bevyengine/bevy

Examples inner documentation and a Bevy Learning Path

Open
#21,212 0 comments 1 reaction 0 assignees View on GitHub
A-Cross-Cutting C-Design-Doc C-Docs X-Needs-SME
Dominant language
Rust
Stars
48.2k
Forks
4.8k
Avg merge
3d 22h
Merged PRs (30d)
161

Description

After using Bevy in [early 2021](https://discord.com/channels/691052431525675048/692648638823923732/820684684836077598) I came back to 0.16, trying to catch up on what has changed.
Since the engine is still in rapid development, things like the bevy book or similar are likely not the best fit and seemingly didn't survive?
However I think with a few templates to follow for the bevy examples, I think a learning path may be achieved pretty frictionless.

# Newcomer experience
The Breakout example is linked on the website and is a nice first start.
But then afterwards I felt a bit lost on how to start digging deeper.

One of the most central examples seems to be **`ecs/ecs_guide.rs`**, but there is no **pointer guiding you to this example**!
I usually end up just searching the keywords I want limited to the `examples/*` and then click trough results until I find code that uses it in an understandable way. (On that note, there are some examples within the individual crates too?)
And once I know what functions or structs are there, I jump into the code to look at their doc comments.
Sometimes ending up in well documented, easily understood piece of code.
Sometimes with really long documentation linking to other documentation.
Sometimes in dead end macros with no documentation to speak of.

# ecs_guide.rs is really nice, other examples not so much
The `ecs/ecs_guide.rs` example is done pretty well.
First there is a fair bit of inner doc, nicely structured, brief, bullet pointed, explaining the goal of the example.
Later down in the example you arrive at more elaborate things like the `SystemSet`.
The Description here is brief but OK given it will be later used and elaborated in the `main()`.
I wanted to read up on the topic of scheduling, as it seems very important in designing the flow of a bevy app.
But the **`ecs/custom_schedule.rs`** example has a very brief inner doc that basically just says "we will use a custom schedule here".

I think I once heard that documentation and comments should describe the developers intent, the part that is not obvious from the code itself.
**Paraphrasing the code** in a simple sentence is great for newcomers getting used to the API.
But it should be followed up by why some bevy functionality is used, what issue it solves and how it helps achieve the goal of the example.

It reminds me of **Godot** where feature requests must contain a concrete use-case that you are working on and how a feature is the only way to unblock you.
Similarly, Bevy's examples should convey the intent: **"When do you use this? What does it help with?"**

# Bevy Learning Path
With more and more features being added, it is hard to figure out what features are critical and which ones are more for optimization purposes or specific use cases. It is equally more easy to fall in the trap of decision paralysis.

I would like to see a bit of a easier entry into learning Bevy.
Not by means of any big book or other document that won't survive the frequently changes.
But by means of just doing what you do already, great examples with useful comments documentation.

Maybe the following:
* A structure template for the inner doc of all examples. Describe the use-case, the main functionalities used to achieve it and a brief run-down of the steps the code will take.
* Curated list of the most important "first stop" examples such as `ecs/ecs_guide.rs` or the Breakout example in the `examples\README.md`. Add some more guidance to the Readme.
* Create a **learning path** in the `examples\README.md` using the existing examples, teaching: Almost always mandatory features, features for corner cases, features for performance optimization, features for debugging or helping in development, etc.. Not all examples may need to be part of this learning path, e.g. 3D rendering effects are pretty stand-alone, you look them up when you want them.

That way, as the engine matures, any new functionality would just need to.
* Stick to a example documentation template rather than having no guiding template.
* Decide if your example is worth adding to the learning path.

So not really much overhead for any PR affected I would assume.

EDIT: shortened it a bit.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.