Restructuring documentation

[andypbarrett]

I want to suggest a restructuring of the documentation. Much of the existing content can be reused. Other stuff needs to be brough up to date to reflect the current API. Then there is missing content. My thought is to use the discussion forum to agree on a structure and "layout". We can then create issues for separate tasks or a plan of attack to avoid clobbering work as a result of restructuring.

My suggestion is something like below.

Overview

Why earthaccess?

Use the text from https://earthaccess.readthedocs.io/en/latest/#overview

Installing earthaccess

_Use current content and add mamba

Getting started

_The intent of this section is to provide a simple example of a search and download workflow to both demonstrate earthaccess and allow new users to get an early success. I think there is too much detail in the current Usage section. This doesn't need to be more than 4 lines of code. The details can be included in the User Guide section.

Contributors

Use existing content

Contributing

A link to the main contributing page(s)

License

Sponsors/Supported by

Not sure if this is needed or what the rule and expectations are.

Not sure if this is required

Level of support

User Guide

_This should include descriptions of the methods/functions in earthaccess.api.py, explaining common usage. _

Authenticating

This would include the three authentication methods

Search for datasets

Search for data

Accessing data

Download data to a local machine/folder

Access data in the cloud

Streaming data to a local machine

Dataset/DAAC specific guides

What other workflows should be included?

How To

How-tos are meant to be short recipes to perform tasks in a workflow. These might include methods described in issues addressing user questions

Tutorials

Complete workflows in a format that allows self-guided learning. Could also include link to Gallery

Reference

API

from docstrings

Modules

Glossary

NASA Terminology

Cloud computing terms

Contributing

[mfisher87]

I'm all about diataxis. I've been tending towards a "diataxis + the really important stuff first" pattern, e.g.:

• Why earthaccess?
• Installation & quick start: Literally the simplest and shortest possible 0-to-data example we can write, then a link to the "tutorials" section for more.
• Citing earthaccess
• Acknowledgements
• Tutorials
  • ...
• How to use earthaccess
  • Search for collections
  • Search for granules
  • Accessing data:
    • ...
  • ...
• How to contribute to earthaccess: How-to's are especially valuable to contributors, so I often find value in having a dedicated section.
  • Set up pre-commit
  • Do a development install
  • Write docstrings
  • ...
• Reference
  • API
  • Glossary
  • ...
• Discussions / Explanations
  • On dataset- and DAAC-specific concerns
  • On authentication: Which strategy is best for me?
  • On similar tools and prior art

The user guide categories you posted, to me, fit really well as how-tos and discussions.

[jessnicwelch]

What is Diátaxis?
The Diátaxis approach divides documentation into four distinct content types:

• Tutorials - Lessons that provide a learning experience, taking users step-by-step through hands-on exercises to build skills and familiarity.
• How-To Guides - Practical guides focused on providing the steps to solve real-world problems.
• Reference - Technical descriptions and factual information about the system, APIs, parameters, etc.
• Explanation - Background information and conceptual discussions that provide context and illuminate topics more broadly.

The key premise of Diátaxis is that each content type serves a different user need and has a distinct purpose. Keeping them separated allows the content to be tailored and structured appropriately for that specific goal.

[jessnicwelch]

@mfisher87 Do you see "Discussion" in your outline as being equivalent to "Explanation" in Diataxis?

[mfisher87]

Yes. I was certain that Diataxis used the term "Discussion", but I must have mis-remembered! :)

[JessicaS11]

Would like to add a pin to have somewhere fairly high level/obvious a citation page. I love citing software, but don't love searching docs pages for 20 minutes to figure out HOW to cite it... it also helps trigger a conversation around how to recognize contributors/maintainers and decide who is or is not an "author" (unless you take the "earthaccess Developers" as the sole author approach).

[mfisher87]

Yeah, I agree. My first thought is to put that next to Acknowledgements, outside of the Diataxis framework. Updated my outline!

Strong +1 on starting the conversation about authorship and recognition; also feel strongly we should have that discussion in an open manner :)