Bevy book revamp: quickstart games and a community-powered Bevy book

[alice-i-cecile]

Rendered

This RFC discusses how we can improve the Bevy Book to include more content and better target the needs of our users.

The most important idea here is to split the users into two paths:

• Example-first: These users want to dive right in, see everything in action and get a working game as quickly as possible. These users often have an idea in their mind that they want to start prototyping as quickly as possible.
• Definition-first: These users want to carefully build up a mental model of Bevy, thoroughly understanding each new concept before moving on. These users tend to be driven by curiosity, or are aiming to carefully develop a new skill.

The first group will use one of several Quick Start guides, while the second group will follow an enhanced version of the Bevy Book.

This RFC outlines how that should work in practice, and provides a helpful set of style guides for this content to ensure we have a consistent authorial voice while allowing much more open contributions.

[colepoirier]

Looks great!

[speakk]

Amazing work creating the outline of the chapters and just all around.

[Nilirad]

This will fix sub-list error in the book chapter list.

[cart]

I love this! I'm sold on the general structure and I really appreciate that you have stepped up to facilitate this effort.

[cart]

I have some concerns about "Bringing it together: {GAME NAME}":

1. Not all sections will feed well into consolidated example games
2. Writing a "complete game tutorial" for each section is a lot of work for authors
3. Reading/following a "complete game tutorial" for each section is a lot of work for readers
4. Building complete games without pulling in "content dependencies from future sections" will be a challenge. Ex: the "A Bevy of Birds" game will likely want to move the birds, but to do that we'll need to pull in Time, which hasn't been covered yet
5. Some sections are clearly tailored around building a thing rather than topical organization. The "Graphics and Assets" section covers Transforms, Hierarchy, 2D (sprites), Assets, Cameras, etc. As we build more features in each of those categories, this section will either balloon in size / scope, or we will need to create new sections (which makes it harder to find content based on topic).
6. Quick Start Games already fill a similar niche (although not identical). Quick Start Games aren't allowed to assume prior knowledge. I think adding "advanced" tutorials that call out prerequisite knowledge would help us fill the "bringing it all together" niche without burdening Bevy Book structure.

I'm currently biased toward the following changes:

1. Remove the "bringing it all together" requirement from sections in favor of small / minimal illustrative examples introduced organically for each concept.
2. Add an "advanced tutorials" concept to cover the "bringing it all together" niche. We could even link to these tutorials from relevant Bevy Book sections.
3. Give each category/engine pillar its own section. Ex: Getting Started, ECS, Assets, 2D, 3D, UI, Input, Time, Plugins, States, Testing, Rendering. In the interest of Bevy Book flow / not burdening users with advanced concepts too early, we could add "advanced" versions of each section near the end (ex: 2. ECS ... 8. Advanced ECS)

[alice-i-cecile]

I agree with these changes. I think we can get a much nicer flow if we're not forced to include cohesive examples throughout (or a strictly linear book order).

The advanced examples sound great; it would be wonderful to be able to assume existing knowledge and focus in on more complex features and workflows.

I'll do my best to refactor this now.

[alice-i-cecile]

@cart I've refactored this as you requested in #23 (comment).

Summary:

1. Removed "bringing it together" complete examples from the book.
2. Added new advanced examples for more complete or sophisticated games that do not assume 0 prior knowledge.
3. Reorganized book to focus on cohesive chapter topics, rather than focusing on the minimal feature set required to get a usable interactive example.
4. Added skippable advanced chapters to the book that are not intended to be read in linear order and cover. Quite a few niche but complex topics (async tasks or writing your own shader) were added due to this added flexibility.
5. Extended the overall topics covered by the book to better fit new organization and point new users in the correct direction. Some of these (like UI or sound) are very minimal due to immaturity.

[Nilirad]

Some thoughts about advanced topics

What about if we add an Appendix or last book section (i.e. a group of chapters) dedicated to covering advanced topics instead of scattering them around the book?

I think it's a good idea because a beginner won't need this knowledge during their first read, but they may need it later, after they've started their work. I know that those chapters/sections are labeled, but they still create a "bubble" that has to be manually skipped and that ruins continuity (there are so many ECS advanced sections that they can make an entire chapter by their own 😄). Advanced topic segregation may also help instructors and learners to point to or find the right resource.

Do some advanced sections really fit into the book?

Bleeding how-to guides

I noticed that the titles of many advanced sections do not refer to topics, but to practical guides to accomplish a particular goal, i.e. how-to guides. In fact some titles could be rendered like "How to render to a texture", "How to write your own shader", "How to deploy on Android". I think they should belong outside of the book, to make them more discoverable, and to not bother the reader that just wants to have an overview of the project with something like: "Hey, do you wanna know how to draw a cube onto a texture?". I think that for the moment, examples are a good place for those guides, even if a dedicated section on the website may be more appropriate in the future.

Bleeding reference docs

We also need to be careful that we don't end up writing API docs in the book. I obviously can't tell precisely from the book summary, but looks like some sections of the ECS chapter, especially the advanced ones, are going a bit too much into a rabbit hole. As a rule of thumb, structuring the sections of a chapter around the structure of the codebase should be a warning flag. We can always link to docs when appropriate though.

The righteous ones

Other sections, however, are genuine topics and deserve to be explained and stay in the book.

[alice-i-cecile]

Those are all totally fair critiques @Nilirad; I've had the same thoughts myself.

Advanced chapters

The problem with moving these out into their own chapters, or into an appendix, is that it dramatically worsens the usability of the book as a reference material. You're going to want to look under ECS; not have to check if it's arbitrarily decided to be advanced or basic.

Topics

So, here are the sections (quick link) that I've included that I think are questionable; feedback on each of these would be helpful:

1. Custom commands: I don't love this organization. It's not clear to new users why they'd want to do that. I think this should be lumped in with exclusive systems and NonSend resources into an "world access" chapter.
2. Custom system parameters: these probably need a note somewhere, but they don't really feel like an ECS thing? They're just sugar
3. QuerySets: I honestly think this should probably just be an aside in the queries chapter.
4. Parallel iteration and component storage optimization: I think these need to be merged into a single "optimizing ECS performance" chapter.
5. Async tasks: Should be moved into Game Logic.
6. System chaining: Honestly, I really dislike this feature, and have yet to see it used to good effect in end user code. Very tempted to cut.
7. Rendering: Tempted to cut or combine wireframe rendering, rendering to a texture and shaders. They're really useful to point people to, but you may be right that they're too immature or detailed.
8. Scenes and reflection: Only kind of belongs under assets. In theory they're an important and useful feature, but they kind of suck to use.

[alice-i-cecile]

I've cleaned up the topic list as discussed above :) In particular, I've added a "performance optimization" chapter for some of these topics, which helps collect them into a useful location towards the end of the book that beginners will naturally skip.

Topic link

@cart, I think I've addressed all of your comments and I'd like to get a basic version of this out for 0.6 to improve the new user experience.

My expectation is that I should be able to write one quick start example (almost certainly Breakout) and all of those book topics done at a basic level over the next few weeks. Advanced examples and more quick start examples can wait IMO; they're nice to have but not essential.

[ValorZard]

We should really have a section to talk about animation, or how to integrate a third party library, since people will have to do that a lot

[alice-i-cecile]

or how to integrate a third party library, since people will have to do that a lot

My feeling is that there are several areas where this is likely to be true for a while: animation, physics, audio and networking all spring to mind.

I'd prefer to avoid discussing specific 3rd party integrations here to reduce maintenance burden and make sure we leave space for new solutions to catch on as they arise.

[cart]

I think we're honing in on a solid structure! I know you're chomping at the bit to get started, so I'll try to provide more immediate responses this review round.

[cart]

I think this is good to go! Congrats on being the first merged RFC!

I've updated the file name to include the PR number based on the discussion in #4.

[cart]

We should update the README to account for this policy. I'll get to that eventually if nobody else does, but it is fair game if anyone wants it :)