first shot at re-organizing sections

[vsoch]

This is a high level re-org of the docs structure! Specifically I've:

• made separate directories to organize jobs, guides, and tutorials
• added a few more FAQ to introduce to flux (and a few more categories)
• simplified a few page headers so they are less texty (we likely will want to do more of this)

I think having these sections will make it easier to, for example, know where to add an LLNL-cluster-specific tutorial, or a link to an integration tutorial, etc. Here are some screenshots of the new TOC and various sections (and some critique for future work):

My critique here is that (although it makes sense to start with install or build) we jump into the quick start assuming the user can relate to these sections. E.g., what the heck is a flux instance? And KVS? What is needed here is an opening paragraph that says "here we are going to install, create X (which is defined as) and then do this (another definition). By the time they get to the sections like "Flux KVS" it should be familiar. We might also rename these headers to be general. E.g., instead of Flux KVS we would say something like "Flux Cluster Information".

Here is the new FAQ - I've added more sections

And tutorials, now also organized

And jobs

And guides!

This should be a high level set of changes, so for discussion here let's talk about the different kinds of content we would eventually want, and if this organization strategy makes sense for that.

Signed-off-by: vsoch vsoch@users.noreply.github.com

[cmoussa1]

Thanks for taking this on @vsoch! I think the re-org has been coming along very nicely. The site is beginning to look a lot cleaner, IMHO.

My critique here is that (although it makes sense to start with install or build) we jump into the quick start assuming the user can relate to these sections. E.g., what the heck is a flux instance? And KVS? What is needed here is an opening paragraph that says "here we are going to install, create X (which is defined as) and then do this (another definition). By the time they get to the sections like "Flux KVS" it should be familiar. We might also rename these headers to be general. E.g., instead of Flux KVS we would say something like "Flux Cluster Information".

I wonder if the site might benefit from a Glossary section, or at least footnotes on pages where definitions are frequent and introduced for the first time, especially in the Quick Start section, which I think you referenced above. Maybe some Flux-specific terms, like Flux KVS or Flux instance, when introduced for the first time, could be a hyperlink to either the bottom of the page or a separate page altogether where each term can be described in more detail. This way, pages like Quick Start remain brief and direct, while also giving users the option to explore our concepts in more detail. Let me know what others think.

I think I also mentioned this very briefly during one of our team meetings a couple of weeks ago, but if it is possible, perhaps we could link our Twitter account to this site in some way? Either with a link to our Profile page, or another page (or sidebar on the home page of our docs site? No idea if it's possible, so sorry if this is a dumb suggestion) that displays our recent tweets/retweets. IMHO, it might give the impression that we are reachable from multiple fronts, both GitHub and social media. Let me know what you think!

All in all, I think this is coming along greatly, and I think we should get some additional feedback from others on the team (especially the folks who took the time to write most of these guides!) :)

[vsoch]

I wonder if the site might benefit from a Glossary section, or at least footnotes on pages where definitions are frequent and introduced for the first time, especially in the Quick Start section, which I think you referenced above. Maybe some Flux-specific terms, like Flux KVS or Flux instance, when introduced for the first time, could be a hyperlink to either the bottom of the page or a separate page altogether where each term can be described in more detail. This way, pages like Quick Start remain brief and direct, while also giving users the option to explore our concepts in more detail. Let me know what others think.

That's a great idea! I often make a terminology /concepts section to reference for exactly this purpose. Do you want to open an issue and are you interested in working on this?

I think I also mentioned this very briefly during one of our team meetings a couple of weeks ago, but if it is possible, perhaps we could link our Twitter account to this site in some way? Either with a link to our Profile page, or another page (or sidebar on the home page of our docs site? No idea if it's possible, so sorry if this is a dumb suggestion) that displays our recent tweets/retweets. IMHO, it might give the impression that we are reachable from multiple fronts, both GitHub and social media. Let me know what you think!

I think I have mixed feelings about this given the state of Twitter - I'd say it's an idea to consider but maybe let's wait a little bit to see if things settle down (or it gets worse). If you want to open another issue that would be great (it's out of scope for the PR here).

All in all, I think this is coming along greatly, and I think we should get some additional feedback from others on the team (especially the folks who took the time to write most of these guides!) :)

Thank you!! I think so too <3

[cmoussa1]

That's a great idea! I often make a terminology /concepts section to reference for exactly this purpose. Do you want to open an issue and are you interested in working on this?

Sounds great, I'll open an issue on this. I can allocate some time for this, sure! I might need some assistance with gathering some good definitions for our terms and glossary, but that could always be discussed in the issue thread.

I think I have mixed feelings about this given the state of Twitter - I'd say it's an idea to consider but maybe let's wait a little bit to see if things settle down (or it gets worse). If you want to open another issue that would be great (it's out of scope for the PR here).

Ah, you're so right - good point. Let's hold off on it for now, and I'll open an issue on it so I don't forget. It can be a very low priority item (if it ever becomes a good idea to add it in the first place 😅).

[garlick]

I really like the glossary idea too! A separate document that could be linked to from the other documents would be wonderful IMHO.

[garlick]

A quick suggestion is to split off the excellent new FAQ entries to a separate PR since that's new content (which I would immediately approve) and topically distinct from the reorg.

[vsoch]

So you want me to do extra work to redo two PRs just for the sake of having two? 😢

[garlick]

At minimum, content changes should be in a different commit than the reorg. It's hard to review a giant diff where things are being moved around and also scan each thing that was touched to see if it was reworded or amended.

[vsoch]

I’ll try to do better next time. Adding those questions was needed for the organization of that page so I placed it in scope. It should still be OK to review if you click “Files” in the PR, the FAQ is just all one file.

[garlick]

Looking at just the faqs page, there are additions, changes, and moves. I can't easily tell if anything changed in the stuff that moved because it looks like a deletion followed by an addition. I'm willing to take your word for it though so yeah, next time please.

Sorry to bum you out. I like the changes so far.

[vsoch]

I didn't change anything for existing questions - there is only moves and new content (green).

[garlick]

Looks great! IMHO we should merge this and keep up the momentum.

[vsoch]

Let's do it! I really want to work on that graphic next. And I'll try to be better about content vs. re-org.