Refining Mimi documentation

[arnavgautam]

Going through the documentation for the first time, there were a handful of things that were confusing.

• Site Navigation

  • Have the "Previous Page" and "Next Page" buttons more prominent, on the top of the screen
  • Minimize links within the documentation, or make it clear that they are branches off of the linear order of the documentation.
    • For example, in Home::Installation, make the last line say "For more complete setup instructions, skip forward to the Installation Guide."
    • Or follow what is already used in Installation Guide::Getting Started, which is just using boldface for the word Tutorials, which indicates that it's a section within the guide the reader should search for
    • Whichever is chosen, make it consistent. Depending on where you look in the docs, section names may currently be hyperlinked, bolded, or even plaintext.
    • It's a small change, but makes it much clearer when going between different pages.

• Sidebar

  • Don't have sections within a single page show up in the sidebar (e.g. Home::Overview, ::Registry, etc)
    • This makes the sidebar expand which means not all contents fit on screen anymore
    • Seeing pages disappear from the sidebar reinforces the notion that you're in a completely different place now, which is very confusing
    • If those can't be removed, add top-level page numbers to differentiate pages from sections
  • The "Tutorials" entry in the sidebar is the only one which is not a clickable link
    • Create a link there pointing to the content which is currently under "Tutorials Intro"

• Content

  • For Home::Mimi Registry, the hyperlink should use https://github.com/mimiframework/MimiRegistry instead of pointing to the Mimi repo
  • For User Guide::Overview, it should say "This guide is organized into seven main sections for understanding how to use Mimi."
  • The section on User Guide::Advanced Topics::Timesteps and available functions, only makes sense after completing the tutorials if the reader has no prior experience with IAMs
    • Maybe include a note saying that people new to IAMs should skip ahead to the Tutorials before coming back to the Advanced Topics
    • This is not completely clear because Advanced Topics comes before Tutorials in linear order. But it doesn't make sense to take Advanced Topics out of the User Guide

I understand that there is less control over parts like the sidebar and above/below navigation buttons, but it still seems worth it to mention potential improvements there in the hopes that one day those can also be improved.

[lrennels]

#708