reorganize top-level site

[grondo]

We have some good documentation on the docs site but the ad-hoc growth of the documentation has resulted in lack of coherence and flow of the overall site. Also given that Flux is starting to be installed as a system RM at this point, we may get many more users that are most interested in "how do I use a cluster running Flux" vs "how do I build this new thing from source and poke at it"

I propose that we reorganize the site in a more straightforward manner given the upcoming user base and at the same time fill in some of the missing high-level documentation. I'll propose a rough outline here with the assumption that we can fill in the gaps as we go along

New TOC proposal: This is a very rough, first-cut draft and others should feel free to come in and edit at will:
(just something to get us started)

• About or Introduction
  • high level introduction (maybe reference but do not incorporate Installation Guide)
  • what is Flux, etc.
• Basics
  • introduction to basic concepts and usage, maybe subsections like:
  • Listing resources
  • Running jobs - interactive, batch, etc
  • Listing jobs
  • URIs and batch jobs
  • Working with job hierarchies
• Administration
  • Installation
  • Flux Administrator's Guide
• Tutorials
  • list specific tutorials here
• References
  • RFCs
  • man pages
  • CORAL
  • CORAL2
  • workflow examples

This puts the more basic information first, following with more detailed topics (like installing from tarballs and running make check) to which first-time users on a system with Flux already installed should not be subjected.

[grondo]

Tagging @ryanday36 and @gonsie for input as they have helped with documentation in the past, and may have a better big picture view of how our docs should be organized, etc.

[vsoch]

@grondo do you want to look at this again with respect to the current organization? I'm happy to do more tweaks if desired!

[vsoch]

Ping again - are we good to close here?

[tpatki]

@vsoch @grondo @chu11 : I think we should revisit this issue.

Based on our discussions today on slack, I have a few suggestions to make about our landing page as well as our docs pages (QuickStart, Building options, etc). I can do some mock-ups or I can try to reorg and submit a PR that we can all review. Thoughts on how to proceed?

[vsoch]

The easiest thing is, if you are comfortable building with make html, to use the site itself as your design mock area, and then we can preview it directly. I can offer to help show you how to do that if needed, probably after this week.