flux-framework
reorganize top-level site
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.
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.
@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 @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?
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.