Issues in the Quick Start Guide

[StefanSalewski]

I recently started studying Bevy -- notice that I am not a English native speaker, so perhaps I just misunderstand a few points?

For me the most serious issue is at https://bevyengine.org/learn/quick-start/getting-started/apps/

What Makes an App? [#](https://bevyengine.org/learn/quick-start/getting-started/apps/#what-makes-an-app)

So, what sort of data does our [App](https://docs.rs/bevy/latest/bevy/app/struct.App.html) really store? Looking at the docs linked, we find three fields: world, schedule, and runner.

Even when reading a second time, I have no idea what "docs linked" refers to exactly. Where is the link? What section of the docs? And "we find three fields: world, schedule, and runner." What fields? Fields in a struct? What struct?

A few other, minor issues:

https://bevyengine.org/learn/quick-start/getting-started/setup/

Create a new Rust executable project [#](https://bevyengine.org/learn/quick-start/getting-started/setup/#create-a-new-rust-executable-project)

First, navigate to a folder where you want to create your new project. Then, run the following command to create a new folder containing our rust executable project:

cargo new my_bevy_game
cd my_bevy_game

Now run cargo run to build and run your project.

For better flow, I would suggest this text:

First, navigate to a folder where you want to create your new project. Then, run the following command to create a new directory containing our rust executable project, and move into it:

cargo new my_bevy_game
cd my_bevy_game

Now type cargo run to build and execute your project.

Build Bevy [#](https://bevyengine.org/learn/quick-start/getting-started/setup/#build-bevy)

Now run cargo run again. The Bevy dependencies should start building. This will take some time as you are essentially building an engine from scratch. You will only need to do a full rebuild once. Every build after this one will be fast!

The use of run ... run is awkward, and build and rebuild is swapped. Better is

Now type cargo run again. The Bevy dependencies should start building. This will take some time as you are essentially building THE WHOLE engine from scratch. You will only need to do a full build once. Every rebuild after this one will be fast!

The last tiny issue is at https://bevyengine.org/learn/quick-start/getting-started/apps/

Nice and simple right? Copy the code above into your main.rs file, then run:

cargo run

in your project folder.

For my feeling, the colon after run is wrong, because the sentence continues. And to avoid duplicate "run" terms, we might better use "then execute".

[StefanSalewski]

One more tiny issue is

https://bevyengine.org/learn/quick-start/getting-started/ecs/

"It often makes sense to break datatypes up in to small pieces to encourage code reuse."

I am quite sure that it should be into, not "in to".

And on the same page we have

"Quick Note: "hello world!" might show up in a different order than it does below. This is because systems run in parallel by default whenever possible."

At least in German language this makes not much sense, because a single entity have no order. I assume it is the same in English. Better would be

""hello world!" might show up in a different position than it does below."

or

"The lines of text might show up in a different order than it does below."

[StefanSalewski]

And at https://bevyengine.org/learn/quick-start/getting-started/plugins/ please replace

To use them all you have to do is:

by

To use them, all you have to do is:

[StefanSalewski]

Note that it would be a good idea to avoid the term "pointers" in https://bevyengine.org/learn/quick-start/getting-started/resources/.

I was very confused by that term here, and had to ask AI to clarify:

In Bevy, "pointers" in this context does not refer to traditional pointers like those in languages such as C or C++. Instead, it is using the term more loosely to describe access wrappers or references.

Explanation:

• Res<T> and ResMut<T> are Bevy-specific wrapper types that allow you to access resources (shared data like Time, Windows, etc.) in a safe and controlled way.
• Res<T> is a wrapper that gives read-only access to the resource of type T.
• ResMut<T> provides mutable access, meaning you can read and modify the resource.

Why Use These Wrappers?

1. Safety: In Rust, direct access to shared resources is controlled to prevent data races. Res and ResMut ensure that only one system can write to a resource at a time, while multiple systems can read concurrently.
2. Convenience: They allow easy access to global state within your systems without requiring you to pass resources around manually.

Clarifying the Term "Pointers":

• While these wrappers aren't pointers in the traditional sense, the documentation uses the term to suggest that Res and ResMut act as handles or references to the underlying resource data.
• The word "pointer" here is more metaphorical, meaning they "point" to the resource data in a way that you can use safely within Bevy's ECS (Entity Component System).

Corrected Understanding of the Sentence:

"Res and ResMut pointers provide read and write access (respectively) to resources."

This means that Res and ResMut provide controlled access (read or write) to the underlying resource data, not literal pointers.

[alice-i-cecile]

Awesome, thank you :)

[StefanSalewski]

Actually, I had not really expected a positive reaction to my remarks -- yesterday I already considered closing it myself again. Sometimes original authors of open source projects thinks that what they wrote is just good enough, or they are very lazy and accept no issues, but only perfect pull requests. But providing perfect PRs is difficult, especially for beginners and non native speakers. The official Rust book would need hundreds of small corrections, but unfortunately the original authors don't care much currently.

[alice-i-cecile]

Hundreds of small corrections is something that we welcome :) Feel free to PR fixes for these, I agree with virtually all of this feedback. Normally I would ask that these be done in separate PRs to avoid controversial changes bogging down simple ones, but I think in this case these are all fine.

The "pointers" bullet point is the only one I would quibble with: an alternate fix there is to call them "smart pointers", with a link to further reading on that term in Rust. Your fix is also an improvement though, and I think superior because it avoids distracting and overwhelming beginners.