Reorganizing the docs sidebar

[saberbrasher]

When writing up my initial UX report on the earthaccess docs, one major discussion point was about how the sidebar currently organizes information and resources. I initially envisioned this being an "issue", but I think some discussion would be better first! I will cc some folks below that I think would be interested (feel free to tag others, please!), and once some chattering has happened I am happy to create the issue for whatever changes are decided.

The current order is as follows:

1. What is earthaccess?
2. Quick Start
3. Work with us
4. Resources
5. User Guide
6. How-to
7. Tutorials
8. User reference

To start the discussion, I suggest instead the following:

1. What is earthaccess?
2. Quick start
3. User Guide
4. User Reference
5. How-to
6. Tutorials
7. Work with us

Justification: The User Guide will likely be a common resource used and seems a logical next place to go after the Quick Start. Assuming the user’s task is more nuanced, the next logical place to go would be the User Reference. Using the functions within, they can build/ manipulate their own code with more tools. I assume the Quick Start would be very popular for elementary users/ people who want a very simple solution. The User Guide is more popular with perhaps intermediate users with more specific needs, and the upper intermediate/ advanced users will likely benefit more from knowing the nuts and bolts of the library. The Resources page I think could become one of the pages in the User Reference drop down as opposed to sitting alone.

cc: @asteiker @andypbarrett @betolink @mfisher87 (any/ all please chime in if this interests you!)

[jhkennedy]

This makes to me. The resources page is especially sparse:

So I definitely agree this would make sense as a section in the User Reference, but mentioned in the user guide.

🤔 Similarly, "Backwards Compatibility" probably makes more sense as a section in the User Reference than the User Guide.

[jhkennedy]

I'm also not clear on the difference between "how to" and "tutorials" having not looked at the docs in a long time.

[mfisher87]

I'm also not clear on the difference between "how to" and "tutorials" having not looked at the docs in a long time.

https://diataxis.fr/tutorials-how-to/#tutorials-how-to

[mfisher87]

🤔 Similarly, "Backwards Compatibility" probably makes more sense as a section in the User Reference than the User Guide.

💯 Maybe "User reference > Policies > Backwards compatibility"? Or is that too nested?

[saberbrasher]

Thanks, @jhkennedy ! I agree with your observations, too. And to your second point - this has come up in a handful of conversations. In particular, I find the "User Guide" and "How-To" sections to have a lot of overlap, and (controversial perhaps) I think they could maybe even be consolidated. The "Tutorials" section I believe was meant to be longer form content and specific examples/ use cases... but I also feel like I remember people mentioning that these docs may not be a good place for that sort of content, and instead could link out to other resources utilizing earthaccess.

[andypbarrett]

Currently, there is overlap between "tutorials" and "how-tos". That is not by design but represents the state of flux of the documentation. A lot of our long-form tutorials just got dumped into that section with no curation or editing. The diataxis page that @mfisher87 shared has a useful distinction that we (I) had in mind when we started with the documentation.

A tutorial serves the needs of the user who is at study. Its obligation is to provide a successful learning experience. A how-to guide serves the needs of the user who is at work. Its obligation is to help the user accomplish a task. These are completely different needs and obligations, and they are why the distinction between tutorials and how-to guides matters: tutorials are learning-oriented, and how-to guides are task-oriented.

I think this distinction is useful and important. One thing I get annoyed with in documentation is having to wade through a lengthy tutorial just to find the two lines of code I need to achieve my goal. That is what a how-to is for. [To provide the one or a few lines of code to get a job done, not to stop me being annoyed - although that is a bonus ;)]

I suggest we spend some hack time sorting through the tutorial content to see what we need to do.

[mfisher87]

To start the discussion, I suggest instead the following:

1. What is earthaccess?

2. Quick start

3. User Guide

4. User Reference

5. How-to

6. Tutorials

7. Work with us

How about:

1. What is earthaccess?
2. Quick start
3. User guide
   • Tutorials
   • How-to
   • Reference
   • Explanation
     • The "Authentication", "Search", "Status" and "Access" pages currently under "User guide" can go here, and I think we should liberally link to these pages from the Modules reference, the quick start, tutorials (following the "ruthlessly minimize explanation" principle and using "See ... explanation for details" language), and elsewhere as needed.
4. Contributor guide
   • Meet-ups / calendar (I feel strongly we should move towards a community calendar Create a community calendar and add it to the docs #1049)
   • How-to
     • How to set up a development environment
     • How to use code quality tooling
     • How to release
     • How to triage issues
   • Reference
     • Code of Conduct
     • Naming conventions
   • Explanation
     • (everything currently under "topics")

I like a model like this because:

• Minimizing top-level categories for easier navigation
• More explicitly categorizing by diataxis audience types
• The things newcomers want are listed first in each category. Quick start has its own top-level section, tutorials are first in the user guide, then how-tos, then reference, moving from things newcomers want to things experienced users want as we go lower.

[saberbrasher]

Thanks, @mfisher87! This is great, I like the idea of breaking things into two "guides" - one for users and one for contributors. My only worry is how deep the nesting may get (or ending up with a ton of things under each sub-header), but maybe that doesn't actually matter so long as things are kept tidy!

[mfisher87]

I think we can get away with 3 levels of nesting, perhaps with exceptions in the future when we have a really good reason to go deeper.

1. Top-level (What is earthaccess, Quick start, User stuff, Contributor stuff)
2. Categories for each type of audience (starting with diataxis categories)
3. Items, e.g. tutorials, how-to guides, reference pages within each category

[andypbarrett]

I think this is a good way to organize the content. Like @saberbrasher, I am a little hesitant about the nesting of tutorials, etc under User Guide because I think it could hide (and require more clicks) to get to important information.

I also think we need a better heading than "explanation". That seems opaque to me.

But I do think I need to digest the diataxis pages again - they seem to have changed a lot since I last looked at them.

[saberbrasher]

If my quick skim of the Diátaxis pages was productive, it sounds like maybe for this section:

• User guide
  • Tutorials
  • How-to
  • Reference
  • Explanation
    • The "Authentication", "Search", "Status" and "Access" pages currently under "User guide" can go here, and I think we should liberally link to these pages from the Modules reference, the quick start, tutorials (following the "ruthlessly minimize explanation" principle and using "See ... explanation for details" language), and elsewhere as needed.

Perhaps instead of "Explanation", the "Authentication", "Search", "Access", and "Status" pages could become a "How-To" page? They already kind of are. They also fit within the "goal oriented" framework, and currently the version of these topics we have in the "User Guide" are pretty brief aside from "Search". I would also have "How-To" above "Tutorials" in this list order. I'm not sure we really have something that fits within the definition of "Explanation" per Diataxis, currently. Maybe one day? I do feel like we have content that makes sense for how the author described "How-to" and "Tutorials", though. And the function library/ API info would naturally fit within how they describe "Reference".

[mfisher87]

I think that would make sense, we could change the page titles to verbs e.g. "Authenticate" ("How to authenticate"), "Search", "Access data", "Check services status".

[mfisher87]

I think this is a clear enough description of a change that it could be converted to an issue. At this stage it could be prototyped, at minimum. What do you all think?

I'm also not 100% sure this should have a needs-decision label. I think it needs refinement and consensus-building for sure, but I don't see any disagreement that needs to be resolved by a governance structure at the moment. @asteiker what do you think?

[asteiker]

@mfisher87 I agree on both points: This feels ready to move to an Issue, and I don't think we need the decision label either - I'll remove now. Should we directly convert to Issue? Or retain this separately?

Also - I'm catching up on this after vacation and love where this is going. Separately I have been developing notes and ideas as part of my CSCCE Community Playbooks training related to our contributor documentation and will soon be ready to convert into new issues. I would like to take the lead on improvements to the contributor section and can leverage the proposed restructuring.

[mfisher87]

Should we directly convert to Issue? Or retain this separately?

I'm not sure of the pros and cons. My instinct is to convert to issue so there's only one place to converse about this idea, but I'm guessing GitHub doesn't do a perfect job when converting 😅

Separately I have been developing notes and ideas as part of my CSCCE Community Playbooks training related to our contributor documentation and will soon be ready to convert into new issues. I would like to take the lead on improvements to the contributor section and can leverage the proposed restructuring.

I want to hear about this! Maybe we could jump on a call for a coffee chat some time soon?

[asteiker]

Yeah my instinct is to convert to Issue too. I'll go ahead and do that.

Maybe we could jump on a call for a coffee chat some time soon?

Absolutely! I want to share at an upcoming bi-weekly hackday as well, but perhaps after the new year. We'll also see each other in person next week - we can try to tag up in NOLA too?

[mfisher87]

That'd be great! I'll send you my cell number on Slack :)

[asteiker]

Converted to new Issue #1162 . This does not copy the comments from this Discussion, but it doesn't close the Discussion either, so we can refer back here.

[mfisher87]

What do you think about using "Lock conversation" to keep all new discussion in the issue?

[asteiker]

Great idea!

[saberbrasher]

All done in #1162 !