mdBook Going Forwards


(Khionu Sybiern) #1

Until 1.0.0, Amethyst will is virtually guaranteed to go under a lot of change. That means the mdBook content will be frequently out of date. Until we hit 1.0, I think it would be more reasonable to assemble the mdBook to reflect that. I’d like to make two proposals to that effect:

  • Rewrite the mdBook to be
    1. a minimal setup guide
    2. a conceptual introduction that gives people what they need to figure the rest out
    3. an aid in tracking the transitions between versions, as to enable early users to keep up
  • Keep a template evolving, using shorthand, to make it so writing the 1.0 mdBook is simply replacing key words and phrases with flushed out text and examples.

With a more minimal book for giving a solid foundation and a template to streamline the 0.X to 1.0 transition, this allows us to write less to support our users. We have to keep track of large portions of the engine and how best to use it, writing less means our catch-up work takes less time to commit.


(Lucio Franco) #2

Could you go more into detail on what aspects of the current book we would keep? And what things would be added?


(Azriel Hoh) #3

Take a moment to read https://www.divio.com/blog/documentation/, it’s good (@distransient linked it in the #documentation channel a while back). What I’d like is perhaps more than one book, but certainly more than one “place” for documentation:

  • Tutorials: The landing book for someone who wants to use Amethyst. This should include the explanation of each concept (usually you should not need code to explain), followed by steps (code, commands to run) that materialize that concept. Be careful not to explain the concept like the reader already understands it.
  • How To’s: A collection of recipes to do specific things. “Making Pong” doesn’t fit in here (it’s a tutorial), but “How to Use Custom Assets” fits.
  • Reference: Similar to the Rust nomicon. Covers how things work internally. Not necessary for someone to use a feature, useful for someone who wants to understand why this feature was built this way.
  • API docs: Rustdoc, this already exists.

Can think of “how to” guides as the generic instructions to use a capability, and tutorials as concrete examples of using multiple capabilities together.


(Khionu Sybiern) #4

Well, I would start from scratch, and use the current book as reference to see what we can reuse or improve. The book feels a bit fragmented, as it has been written and improved upon over time, mostly as needed. A fresh start by the documentation team would enable us to give a more consistent voice and depth.

I like it, though it doesn’t feel like it would go well with how I proposed approaching the streamline writing. It may still meet the objective if we were to forego Tutorials in favour of a larger set and quality of How To’s. How To’s would be more focused and generally shorter than a tutorial, which is better for keeping up to date and for presenting more information. We could always have our Getting Started include a series of How To “slices”, ie “for creating basic systems, refer to sections 2 through 5 of…”. Less beginner friendly, but with the state of the engine overall, I think it would be less of a priority to cater to beginners as much as people who have a certain minimal amount of Rust or programming experience.

Reference should be where we give the most priority to, as we’ll also need them to write the Tutorials and How To’s.


(Lucio Franco) #5

Sure, I think this would also be a good opportunity to move the book to its own repo and have it under amethyst/book. That way we can work on the new book while keeping the old one.


(Khionu Sybiern) #6

True. We already have amethyst/documentation, actually.


(Joël Lupien) #7

Don’t delete the concept section :3
I’m very attached to it…


(Khionu Sybiern) #8

It would become the Reference section.


(Khionu Sybiern) #9

At least, according to the separation that Azriel’s link laid out.