Lets face it, the amethyst book has a bunch of layout problems. While it contains a lot of good information, it has an inconsistent layout and is often hard to navigate. When reading this please keep in mind that this list is not complete, some of these things may have already been fixed on master, and I am a hypocrite.
Non-exhaustive list of layout issues
- It can’t seem to decide if it wants to be documentation or a tutorial. Instead of explaining each part of how to use certain systems, the book sometimes opts to use a tutorial step by step style. This can be seen in 11. Sprites. Tutorials are not inherently bad, but it is still important to include some more detailed information about each part and the options they include. Unfortunately, the documentation is extremely sparse in this area. As far as I can tell, 11.1. Set Up The Render Pass is the only page on setting up a rendering pass, but it only contains two sentence of explanation for a two line code snippit. Rendering could easily be its own entire section or even book, but instead is limited to just this tiny page. I understand that these things take time and Amethyst has limited resources, but this is a bit of a disappointment considering Sprites has been part of the book since Amethyst 0.8.0.
Sections don’t follow a naming conventions. I counted 10 pages that were titled “How to Define…”. The entire book is meant to be a how to guide so prefixing every page with “How to” would get very repetitive, very fast. That’s why naming conventions prefer the much more concise forms.
- How to Define Prefabs can be simplified to Defining Prefabs
- Having a bunch of sections named Bla: A, Bla: B, Bla: C, etc. is probably a good indicator that you need to create a new section Bla to put A, B, and C into. *Cough* How to Define Prefabs *Cough*
- It looked fine on github… Better quality control is needed to make sure formatting is correct and conventions are followed. 8.5. How to Define Prefabs: Adapter and a few other pages contain malformed links that can be seen on both github and in the released version of the amethyst book.
- Dangling Pages Why does 5. Math get its own top level section? It only contains 3 sentences and would make much more sense under 2. Getting Started in an ‘Associated Crates’ page along with links to the other main dependencies of amethyst and other useful utilities.
- Irrelevant Pages Who is the amethyst book for? While the vast majority of pages seem to be written for Amethyst Users, other pages such as 12. Testing contain information for the Amethyst development team. Even though users of the Amethyst crate may find it somewhat beneficial, when reading the page it becomes clear that the page was not written for them.
Pages are way too long. Some pages contain too much information and should really be split into smaller sections.
- Bad Example: 3.5. System. Only a third of the page is specific to systems. The sections Accessing the context of the game, Manipulating the structure of entities, and Changing states through resources can be generalized to better describe how the same actions can be done in many places such as Systems, States, and anywhere else you have a reference to World.
- Good Example: The general rule of thumb when writing a page is ‘Will readers need/want to read through the entire page?’. For example look at rust’s explanation of comments: 3.4. Comments. It is simple, to the point, and gives you just enough to get started. It is not an exhaustive explanation of every type of comment. It also has one sentence at the end of the page mentioning that other types exist and what specific page to look at to read about them. In this way, the comments page only contains just what a reader needs/wants to know in order to write a comment. However longer pages also have their merits. Pages like 2. Programming a Guessing Game can afford to be as long as they are because the reader is likely to read the entire page as part of the tutorial. In that case, combining them into one page makes it easier to read by not breaking up the tutorial.
- Concepts is not conceptual. It contains a bunch of code and specific details on how to use very specific parts of Amethyst such as ECS.
I think the Amethyst Book should be its own repository. An argument could be made that keeping the book with the code allows for commits to be made to both at the same time, keeping the book up to date. My counter argument: That doesn’t happen very often and the vast majority of commits I have seen only update one or the other. Splitting them would also make it a little easier for people (like me) to contribute to the book.
While the addition of more content would be nice, the main purpose of this post is to request that what is already there be reorganized. Many pages are already split into subsections that can be moved around and I don’t see any reason to throw away any of the parts we already have.