bevyengine / bevyengine/bevy-website
Tracking issue: new book
- 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
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