Refocus
I'm writing down some thoughts on how we might improve the book.
Style
Let's let The Rust Book be our guide! This might mean
- Less nesting. Notice that the Rust Book only nests one level deep. Redox Book goes to 3. A flatter structure is more book-like.
- Fewer, longer sections. Some of our sections are quite short.
- Focus on the reader. Take them on a coherent journey that doesn't meander. Build one thing on top of another.
Maintainability
We're a small community, so we'll need to be smart about what we pick.
- Fewer "lists". Dynamic content, highly specific details shouldn't go in the book. We can auto-generate those and put them on a section of the website or a more "docs"-looking documentation page. Stuff like: the list of schemes, the list of contributors.
- Higher-level. The content shouldn't need rewriting when some little component changes.
- Testability. If the book is a walkthrough of some sort, we should be able to script the underlying commands end-to-end.
- Automation. Here we might consider how users without backend access could build something easily deployable. A container, perhaps, or a well-structured tar file. Are there any other web server configs that could be prepared by CI? See #137 (closed)
Goals
The book doesn't have to do everything, or answer every question. Perhaps no answer is better than the wrong answer.
I don't think we need a ground-up rewrite so much as an aggressive refactoring. Clear away some cruft, edit for style and coherence, open issues on the website repo for things that really belong over there, etc. After all that, we can see where we're at.
What do you all think?