Reorganize information on the computing resources and software environments

[DavidT3]

Pretending to be a new user again (not that difficult given I only started a few weeks ago), I think that the information regarding what computing resources and software environments are available should be re-organized. There is some small amount of replication, and some information missing that you might expect based on the title of the docs section (for instance the actual quantification of computing resource options, listing CPU and memory) is in the section labelled (in the menu on the left of the docs) 'Fornax Science Console Capabilities', and not in 'Server and Environment Options'.

The 'Server and Environment Options' text does link back to the specific definition of what resources are available to each compute option, but I think it would make more sense the other way around.

My thoughts:

1. We merge the 'Fornax User Documentation' landing page and the 'Fornax Science Console Capabilities' pages into a combined landing page, and cut down the 'Computing Resources' section to be one line summaries rather than specifics (e.g. simply state there are several options of compute scale available, and direct them to a whole section dedicated to that information for specifics). I think merging those two overall sections make sense, as they are doing quite similar things - introducing what Fornax is and why it exists.
2. Change the 'Server and Environment Options' section to 'Choosing a Server' or some such thing, and focus just on the compute choices, possibly including the storage information as well. Remove the description of software environments other than a segue to the 'compute environments' section, which should follow immediately after the section discussing compute options.
3. This software environments section first discusses the choices of image - default astro vs high energy astro - and from there naturally branches into discussion of what software are available within each image.

I think this consolidation is important, because in my opinion users are more likely to look for the category of information they want in the sections ToC on the left, rather than reading through all the pages carefully and sequentially.

I am going to start working on this, I think it'll be easier to communicate what I mean by just demonstrating it, and also from the HEASARC point of view we need to get better/any descriptions of how to use the high-energy software conda environments into these docs before the ESRR starts in earnest.

[zoghbi-a]

If you are making changes, I suggest making them incremental to make it easy to review. From today's meeting, it looks like @vandesai1 and @troyraen are also thinking of/doing some re-organization, so the changes should be coordinated.

[troyraen]

Thanks @DavidT3 and @zoghbi-a. Yes let's discuss it. We chose the current sections and ordering for a few reasons but also saw that some of these issues still exist and planned another round of edits to improve it. I believe @vandesai1 is working on that now. I'll touch base with her and make sure she sees this. In the meantime, here are my thoughts.

1.a. I agree that the separation between the two pages is not as clear as it could be and I think Vandana is planning to address that. I do think they should be separate pages. The main page (Fornax User Documentation landing page) needs to introduce several things, so will definitely be more broad than just introducing the console.

1.b. The Fornax Science Console Capabilities page is intended for people who are wondering whether they want an account. The idea is for those folks to see everything they need to make that decision on this page. So I think the server sizes, at least, should appear here. I could imagine moving most of the descriptions to the Server and Environment Options page but then we would need to list the server sizes there as well. Duplicating the sizes on two pages wouldn't be the end of the world but I'd prefer not to because makes it harder to keep the docs updated and in sync. I agree that it's a bit strange to only see a link to this info on the Server and Environment Options page rather than the info itself, but that's why we left all of it together and on the Capabilities page for now.

2. This page is about the two choices the user has to make in order to start a console session: Server Type and Environment. Here, "Environment" really means the image -- This "environment" is much different than the environments discussed on the Compute Environments page and I know that's confusing so I tried to help by calling this one the "Base Environment" in the section heading and text. If the screenshot itself (really, the console start-up page) said "Image" or similar instead of "Environment" then we could use that same terminology for this page title and content and I think that would reduce confusion.

3. Users don't encounter the environments that are discussed on the Compute Environments page until after they've already started a console session and found their way around JupyterLab and how to run notebooks / develop code. Since they both encounter these much later than the choice of base environment (=image) and interact with these very differently than the base environment, to me it makes the most sense to have the content separated and ordered more like it is now.

What do you think about all of that?