Book critique notes

[viridia]

Reading through the whole text of The Book, and noting things as I go:

General:

• Missing sections for Graphics, Audio, User Interface, etc.
  • Status: out of scope

In intro/what-is-bevy/:

• "Bevy is a modern, ECS-first game engine written in Rust". This comes before the explanation of what ECS is. How about we just drop that bit and say "Bevy is a modern game engine written in Rust"

In intro/the-three-letters/:

• The "database metaphor" is mentioned in several chapters, including this intro/the-three-letters/, storing-data/entities-components/ and storing-data/world/. But there are problems:
  • Each chapter talks about the concept as if it were being introduced for the first time, despite the fact that we've already talked about it in previous chapters.
  • There's a lot of redundancy and repetition in the different explanations.
  • The explanation in storing-data/entities-components/ is the clearest of the three, however the one in storing-data/world/ introduces the concept of archetypes.
  • We should trim down these sections to include only the new ideas and not re-explain the concept every time; we can refer to the database metaphor via link to previous sections.
  • There are also a couple of other places where the database metaphor is referenced, but are clearly written in a way that implies that the concept has already been introduced in previous sections. These are OK but should have links.
• Status: TODO

In intro/the-three-letters/

• Consider adding a final section, "Why ECS?". This can talk about the benefits of performance, and reuse via composability. We should probably also note that the maximum benefit of ECS can only be achieved by adopting an ECS mindset.
• Status: #2166

In storing-data/local-system-param/

• I would put this section last in storing-data, because this feature is so rarely used; at the very least it should come after resources and relations
• Status: #2167

In control-flow/systems/

• Lots of bad links
• Needs more examples, but fewer inline examples
• Status: TODO

In control-flow/run-conditions/

• Needs lots more examples
• Status: TODO

In control-flow/commands/

• Examples please
  • Status: TODO

In the-game-loop/app/

• Show example of plugin registration
• Status: #2179

In architecture/

• I'd like to find a better word than "architecture" here, or at least call it "High-level architecture".
• Status: #2164

In architecture/states/

• I think this section would be better placed under "Control Flow" or "The Game Loop"
• Status: #2164

In best-practices/

• This section isn't really so much about best practices (how to achieve engineering quality), it's about developer happiness. Maybe rename to "Productive Development" or "Development Tips"?
• Status: #2163

@alice-i-cecile @theotherphil

[viridia]

Thinking about this some more, I would rename the "architecture" section to "modular design", and move the "states" section under "control flow".

[viridia]

Another idea: in the "What is Bevy?" section, add the following:

Let's Get Serious

Although Bevy bills itself as a game engine, you can use for other things than just games. Game engines in general, and Bevy in particular, have been used as a basis for "serious" apps in the scientific and engineering domain.

Game engines are, at their core, high-performance, real-time simulators coupled with a framework for producing high-fidelity graphics and immersive sound. Game engines are designed to squeeze every last drop of performance out of the available hardware (both CPU and GPU). The fruits of this labor are just as applicable to data visualization and computer-aided design as they are to building entertainment products.

Implemented in #2165.

[alice-i-cecile]

Missing sections for Graphics, Audio, User Interface, etc.

This was deliberately cut from the MVP for scope :) Definitely agree that these are essential, but unlike the other complaints, I'm not going to block on this for launch.

[alice-i-cecile]

This section isn't really so much about best practices (how to achieve engineering quality), it's about developer happiness. Maybe rename to "Productive Development" or "Development Tips"?

I think this needs to be split into "development practices" and "releasing a Bevy game" 🤔