Layout Grievances for the Amethyst Book

(Jasper) #1

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.

Sidenote

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.

Edit (Clarification):

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.

4 Likes
(Kel) #2

It would be nice to have the book in a separate repository in terms of making the PR process far lighter, but I think that the benefits of having it alongside the code far outweighs the costs. These are super good criticisms though. I think there’s a lot of good stuff in the book, it might just need one or more editorial passes to move things around based on relevance and intention. Thanks for putting all of this together! Your post will be a helpful companion in the editorial process.

1 Like
(Jasper) #3

I think that most of these will just require someone to go through one by one and just check that it looks correct. However other areas such as Documentation vs Tutorial shifts may require larger additions
to complete.

I would also like to stress the importance of making this book easy to read.

This may be a bit controversial, but in its current state the Amethyst Book is not a very helpful tool for solving issues in my code and learning how to get started. I found that the examples on github and associated APIs where vastly more helpful for solving problems and learning how stuff worked.

1 Like
(Jasper) #4

It just occurred to me to ask, but who is Amethyst’s target user base? Are there any knowledge expectations of users who are just starting to use Amethyst (excluding rust)?

I started learning Amethyst in my senior year of high school a while after learning how to use Rust. The things I want to get out of the Amethyst book are likely very different from those of a professional developer (game or otherwise). As a student, the rendering passes were a new concept for me which caused some frustration due to a lack of good documentation. However this might not be a concern if the target user base has some experience in the area.

1 Like
(Kel) #5

I think currently it’s probably worth assuming decent knowledge of Rust, given the unstable growth “beta” state the engine’s in.

2 Likes
(Théo Degioanni) #6

I am pretty sure this was written for Amethyst users. What exactly makes you believe that?

It’s been pretty difficult to explain the concepts to users without code to accompany it. Without it, people tend to have a very disconnected understanding of the engine, and while they understood the local aspects of the concept, they do not know how it fits in in practice. To me, concepts help understanding code and code helps understanding concepts.

So far something I have noticed is that people seem to learn very differently, and one might like something somebody else might despise. This is going something that is going to be very tricky to integrate into the book.

1 Like
(Zicklag) #7

I think that is very likely true. If you look at Rust itself, they actually have at least three different ways to get started learning Rust on their “learn” page. That might be something to think about. If we can find out what perspectives on Amethyst are useful to people getting started with Amethyst we could create a couple of different ways to go about learning how to use it.

(Jasper) #8

I may have misread that one. Here is the quote I was originally looking at.

12. Testing:
… Amethyst contains many concepts for you to understand and remember. During development, normally each concept’s types are written in its own module.

The amethyst_test crate provides support to write tests ergonomically and expressively.

I had assumed that “each concept’s types” was referring to the types in the amethyst library instead of user defined types.

I agree, but the concepts section should be reserved for only the information that is essential to understanding the rest of the book. For instance, changing states through resources is useful information, but it is in no way necessary for understanding what follows. Also if concepts were the right place to put it, why is it under Systems? The code example for that section is fairly lengthy and it looks like the author got a bit carried away when explaining concepts.

Also one page even starts with a disclaimer saying that it isn’t necessary for understanding the reset of the book. In my opinion this introduces extra complexity before the reader has a good understanding of the base concept.

3.7. Event Channel
While it is not essential to understand it to use amethyst, it can make your life much much easier in a lot of situations where using only data would make your code too complex.

Side note: We need to start doing grammar checks

1 Like
(Abovegame) #9

Indeed the Amethyst book should be improved and it most likely will. The way i see it, it should explain all the concepts to the average user in as much detail as possible, and this should represent the first elementary part of the book. The second part of the book could be all these concepts actually used in game examples, in short a game tutorial. This way someone could jump straight to the game tutorials if he has some understanding of the engine, otherwise he should start with the first part of the book.As for the third part of the book it could be only for people interested in contributing to further development.

Anyhow i can confirm that some code snippets in the book helped me understand a bit more how things should be done.