Documentation portal proposal


(Kel) #1

I’ve discussed this previously with some folk in the discord, but I figured it would be best to start a post here to contain discussion before actionable issues may be opened. This is going to based on the guidelines from this blogpost by Daniele Procida, which is as follows:

  • Tutorials
    • Learning oriented
    • Allows newcomer to get started
    • Teaches lesson
  • How To Guides
    • Goal oriented
    • Shows how to solve a specific problem
    • Is a series of steps
  • Explanation
    • Understanding oriented
    • Provides background and context
    • [Helps build a bigger picture of the pieces]
  • Reference
    • Information oriented
    • Describes the machinery
    • Is accurate and complete

What we have now

Currently, Amethyst documentation lives under the following directories:

  • Main portal: /doc
  • API docs: /doc/{latest,master}/doc/[crate]
  • Book: /book/{latest,master}

(consider these as directories in the domain of the website being accessed)


What I propose

However, I’d like to propose a rearrangement of this structure so that each published tag may have its own published portal, replete with relative links between the different sections (eg, Master book links to Master API docs while X.X book links to X.X API docs). Consider the following directory structure:

  • /doc
    • As it is now. Links to different versions of the docs
    • Helps users quickly find what they’re looking for
  • /doc/{version}
    • Base of portal for that version with summary of docs included and links to the code and documentation for that version of Amethyst
    • Could be master, latest, or any git tag
  • /doc/{version}/api
    • Home of rustdoc reference information
    • Currently /doc/{latest,master}/doc returns a 404. It would be desirable that the base directory for the API at least redirect to the amethyst base crate directory.
  • /doc/{version}/book
    • Home of mdbook, featuring architectural explanations and the Pong tutorial

And, in the future, more may be added to this /doc/{version} directory, such as guides (like quick reference pages), or information that may be split off from the book (where it might be desirable, I’m not sure, but it’s worth not ruling out). These portals may also use a navigation mechanism similar to the navbar used on the rustsim websites, such as nalgebra.org. It’s from this first step that we can build a Documentation infrastructure that helps users find what they need for their version of Amethyst more easily and more quickly.


Barriers to overcome

Such a change would not only invalidate links that may need redirects generated, but could also complicate the build process. It might be desirable to provide a script in the base repository itself to build all the documentation portal for the current tree, so that when handed environment variables it may handle building the webpage tree for use in the website, and otherwise build offline docs for users.

Documentation changes also require a certain time investment since these changes are under the processes of core repository PR’s, and invariably become integration tests, whether it’s for CI or green users to “run” those tests. These things aren’t necessarily bad, they’re just… necessary. Because of this it’s fairly necessary to plan out this structure moving forward to keep this process smooth.


DRAFT: Amethyst 0.11.0 release
(Azriel Hoh) #2

The base directory structure is on point :ok_hand:.

For the book, we don’t have a very good landing, or a good flow. The Rust book goes with:

  1. Intro
  2. Set up / Hello World tutorial
  3. More complicated tutorial
  4. Guides
  5. More Guides
  6. Tutorials
  7. More Guides
  8. Giant tutorial
  9. Appendix

If we look at how each section (grouping of pages) is structured, it mostly goes like this:

Section Introduction

  1. Explanation with examples (small snippets) - mini how-to
  2. More in depth explanation, more examples - how-to do more advanced stuff

OR like this:

Tutorial

  1. Tutorial part 1, some explanation
  2. Tutorial part 2, some explanation

Most of their pages are how-to guides, with heaps of explanation, and they don’t mix the two types of sections. Presumably we don’t need to split the book, since all our reference stuff is under api.

Being a little off point, I do think we’re missing a simpler “Hello World” tutorial though.


(Fletcher) #3

Is this something you would want on Github Pages?


(Kel) #4

Yeah I don’t think anything in the book necessarily needs split off right now. But it might be useful in the future, because I think it’s important to consider the book’s structure like a book. I think it should be structured such that a user could sit down and follow it from front to back and understand a broad scope version of the project, how to begin writing their own Amethyst application, and generally how to use each of the discrete API surfaces within Amethyst (so they may confidently jump into the API reference thereafter), all without unnecessary extras inbetween.

I don’t think this is off topic at all. As we bring structure to our docs I think it will help expose places where we can improve!

Some parts, yes. For example, the core portal linking to the different versions of the docs will remain on the website repository, and the actual calls themselves to the building of docs will remain in that script, and probably have to be changed a bit there. Redirects, where they may occur on Github Pages, must also be added as described here. Everything else would go on the core repository, including some of the doc portal build script.