bevyengine / bevyengine/bevy-website

Tracking issue: new book

Open
#265 13 comments 17 reactions 0 assignees View on GitHub
C-Tracking-Issue
Dominant language
JavaScript
Stars
249
Forks
450
Avg merge
16h 20m
Merged PRs (30d)
6

Description

As I'm sure the audience is aware, the current book is *very* short. Naively extending it wasn't going to lead to great outcomes, so this [RFC](https://github.com/bevyengine/rfcs/blob/main/rfcs/23-quick_start_book.md) for a new structure [was approved](https://github.com/bevyengine/rfcs/pull/23)!

So, how do we get there? So far, we've:
- created a `new-book` branch that we can safely work off of
- written (and reviewed!) some draft chapters

However, this process sucked, for several reasons:
1. Shortcodes are miserable to write, buggy, require authors to learn a custom DSL, have limited functionality, and make reading the raw code very hard. This is bad for both authors and reviewers.
2. Reviewing an entire chapter at a time means that the turn-around on PRs is super long, and reviewing is very hard.
3. Code samples would regularly break in dumb or subtle ways, as they weren't being compiled. This also made them a lot harder to write effectively.
4. We didn't have a proper style guide in any form.

Overall, this made the process slow, painful and inaccessible. I want to change that. On the technical / process side, I want to:

- [x] Rebase the `new-book` branch.
- [x] Replace short codes with links (#272).
- [x] Make the doc links pretty, like our current links (#273).
- Extend with #200?
- [x] #207, for quality assurance
- [x] #83, to make sure our code actually works (and continues to work!).
- [ ] #279, to make sure our code is pretty
- [ ] Write a basic style guide for the book, which links to the RFC.

In terms of content, I would like to:
- [ ] pick two or three games, and create high-quality tutorials to them that assume 0 Bevy knowledge
- [ ] merge the Welcome chapter, and give it final polish review
- [ ] merge and polish the ECS chapter
- [ ] finish the game logic chapter
- [ ] add a rendering chapter
- [ ] add an assets chapter
- [ ] add an input chapter

Everything else is non-essential (or, like audio and UI, too immature); if you want to work on another chapter feel free, but I don't think we should block the book release for it.

Contributor guide

Open the contributing guide

Research direction

Start with the linked quick-start book RFC and review the unchecked items in this tracking issue, including the style guide and planned chapters. The issue does not name implementation files or tests; work is complete when a specific book task is finished and its corresponding checklist item can be marked done.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
20/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.