User Reference Reorganization

[saberbrasher]

The current User Reference organization could improve (unclear when a user should go to API > Search and Access vs. Modules > any nested sub-pages) creating confusion about where the “authoritative” information lives.

Organization of ALL sidebar entries is currently being discussed here: #1133

Function argument details that a user will encounter in other doc pages (e.g., cloud_hosted) are located within nested docs (to find 'cloud_hosted', a user needs to go to User Reference > Modules > Collections > Collection Queries). This is just one example, but unless the user is already familiar with earthaccess and how it works, I doubt they would know where to look to find more details on that functionality or understand why things are organized the way they are. Some of the functions within the nested sections also still have "placeholder" text for descriptions... see #597.

Here are my recommendations to start the discussion:

1. Merge the User Reference nested pages (minus the Glossary) into a single API Reference page that serves as a searchable function library.
2. Consider renaming this new page something clearly descriptive (API Reference, API Functionalities, Function Library.... I dunno).
3. Ensure this page contains ALL parameters of functions within the library so that all options are obvious and explicit and fill in any placeholder text that remains.

Justification:
Users will have one clear, authoritative place to look for functions/ parameters/ defaults, etc. This reduces redundancy, makes the info easy to link to, and makes navigation more intuitive.

What do folks think about this? Again, I am happy to create the issue once some chatter has happened! Any and all jump in, please! ccing a few below.

cc: @andypbarrett @mfisher87 @betolink @asteiker @jhkennedy @danielfromearth

[mfisher87]

💯

Merging "API" and "Modules" sections in to one section is the only choice that makes sense to me :)

I'm not sure I agree one the "single page" approach because I dislike scrolling through really long pages. That's just me, though. It'd be interested to see how users feel! I don't think we need to be rigorous about that, we could ask the question on Zulip as an emoji poll (and remind Slack users to register for Zulip ;) )

Perhaps we can do this in steps: First, move everything in "Modules" into "API", then consider merging everything together.

If we do go the single page route, I think we should pay more attention to the headers in that page so the table of contents on the right side of the page is usable as a navigation aid.

Ensure this page contains ALL parameters of functions within the library so that all options are obvious and explicit and fill in any placeholder text that remains.

100% agree, but I think we should consider these separate efforts. I think they are cleanly separable and parallelizable as the reorganization requires changes to the docs, and improving comprehensiveness requires changing docstrings in the codebase. The reorganization effort is much less work, and I wouldn't like for it to be slowed down by the more expensive effort to be more comprehensive with our docstrings!

[saberbrasher]

This sounds good, @mfisher87! I agree that attacking this as two issues (1: reorg, 2: fill in all placeholders) is probably best to keep things moving along. Single page does not bother me so long as it is well organized/ has nice headers/ has a table of contents like you said, but sure! I am one of those slack users who is not on zulip. :-) So many ways to yap at people these days . What would you propose as another way to organize things (if not on one comprehensive page)?

[mfisher87]

I think a good option might be to organize by the categories we currently define in the user guide: Authentication, Search & Access (I feel these overlap because access depends on the results of a search), and Status.

[mfisher87]

How does everyone feel about converting this to an issue? I think it's actionable (prototypable at minimum)