How should we modify the files and directories structure?

[ronnyhdez]

Docs categories inventory

As of: 2026-04-01

Questions about structure

This doesn't affect any functionality, but I would like to see a naming
convention for the file names. Not mixing camel case with snake case.

If there is a folder like tutorials, does the author of a notebook should
include support images in a general folder images in that directory or
should we ask for authors to PR a self-contained folder per tutorial? i.e.:

• tutorial_folder/
  |- img/
  |- notebook.ipynb
  |- internal_function.py
  |- dependencies.txt

Is the examples folder structure per centre? Is this something that we
should document in the contributing section for somebody who would like to
contribute an example notebook?

examples
├── data
│   └── gulf.json
├── GESDISC
│   └── GESDISC_MERRA2_tavg1_2d_flx_Nx__Kerchunk.ipynb
├── images
│   ├── earthaccess-intro.png
│   └── subsetting_diagram.png
├── img
│   └── Worldview-snapshot-Ida.jpeg
├── index.qmd
├── LPDAAC
│   ├── Find_and_Access_HLS_PointBuffer.ipynb
│   └── LPDAAC_ECOSTRESS_LSTE__Kerchunk.ipynb
├── NSIDC
│   ├── cmr_auth.py
│   ├── cmr_serializer.py
│   ├── environment.yml
│   ├── ICESat2-CMR-AWS-S3.ipynb
│   ├── ICESat2-CMR-OnPrem-vs-Cloud.ipynb
│   ├── img
│   │   ├── cloud-model.png
│   │   └── download-model.png
│   └── IS2.py
├── ORNL
│   ├── Data_Access__Direct_S3_Access__ORNL_DAYMET.ipynb
│   └── ORNL_DAYMET__Kerchunk.ipynb
├── PODAAC
│   └── PODAAC_ECCO_SSH__Kerchunk.ipynb
├── Transform-workflow.ipynb
└── USGS_Landsat
    └── Landsat_C2_Search_Access.ipynb

I like the structure of how-to folder. There are files which seems to be
general and then we have two folders: access_data and find_data. This could
be a good option to make more intuitive what kind of topics we want per each
category.

There is the examples and also the workshops. I'm not sure how this should be handled or if there should be another category for this type of files. In the workshops there is a setup and then the index to list workshops.

---

Tutorials

There are files in the tutorial folder, and also the ones in the external.
in total there are ~22 files in this category.

Main Tutorials Directory

• tutorials/index.qmd
• tutorials/Earthdata-cloud-clinic.ipynb
• tutorials/Hurricanes_Wind_and_Sea_Surface_Temperature.ipynb
• tutorials/Sea_Level_Rise.ipynb
• tutorials/Above_Ground_Biomass_Density.ipynb
• tutorials/Observing_Seasonal_Ag_Changes.ipynb
• tutorials/Harmony.ipynb
• tutorials/Earthdata_Cloud__Data_Access_OPeNDAP_Example.ipynb
• tutorials/fair-workflow-geoweaver-demo.ipynb
• tutorials/matlab.qmd
• tutorials/Data_stories_template.ipynb
• tutorials/make_atl03_figure.ipynb

External tutorials

• external/appeears_csv_cloud_access.ipynb
• external/cof-zarr-reformat.ipynb
• external/data_access_direct_S3.ipynb
• external/nasa_earthdata_authentication.ipynb
• external/data_discovery_cmr.ipynb
• external/data_discovery_cmr-stac_api.ipynb
• external/harmony_subsetting.ipynb
• external/on-prem_cloud.ipynb
• external/sentinel-6_opendap_access_gridding.ipynb
• external/zarr-eosdis-store.ipynb
• external/xarray.ipynb

Examples and workshops

I'm not sure if this one should go in the tutorials category, but a bit similar
to the other ones. There are ~14

Example workflows

• examples/index.qmd
• examples/Transform-workflow.ipynb
• examples/GESDISC/GESDISC_MERRA2_tavg1_2d_flx_Nx__Kerchunk.ipynb
• examples/LPDAAC/Find_and_Access_HLS_PointBuffer.ipynb
• examples/LPDAAC/LPDAAC_ECOSTRESS_LSTE__Kerchunk.ipynb
• examples/NSIDC/ICESat2-CMR-AWS-S3.ipynb
• examples/NSIDC/ICESat2-CMR-OnPrem-vs-Cloud.ipynb
• examples/ORNL/ORNL_DAYMET__Kerchunk.ipynb
• examples/ORNL/Data_Access__Direct_S3_Access__ORNL_DAYMET.ipynb
• examples/PODAAC/PODAAC_ECCO_SSH__Kerchunk.ipynb
• examples/USGS_Landsat/Landsat_C2_Search_Access.ipynb

Workshop Materials

• workshops/index.qmd
• workshops/setup.md

How-to guides

The file structure in this category is easier to follow. gg

Main How-tos directory

• how-tos/aggregate.qmd
• how-tos/Earthdata_Cloud__Open-Science-Tutorial.ipynb
• how-tos/reformat.qmd
• how-tos/reproject_regrid.qmd
• how-tos/subset.qmd
• how-tos/plot.qmd
• how-tos/use_apis.qmd
• how-tos/read_data.qmd
• how-tos/using-s3-storage.ipynb
• how-tos/how_to_guide_parking_lot.qmd

Find data

• how-tos/find-data/earthdata_search.md
• how-tos/find-data/find-python.ipynb
• how-tos/find-data/find-r.qmd
• how-tos/find-data/CMR-STAC-Search.qmd
• how-tos/find-data/programmatic.qmd

Access data

• how-tos/access-data/access-cloud-python.ipynb
• how-tos/access-data/access-local-python.ipynb
• how-tos/access-data/access-local-opendap.qmd
• how-tos/access-data/access-command-line.md

[ateucher]

Thanks for starting this @ronnyhdez, great thoughts! Here is a structure that the mentors came up with in January 2025:

Current & Envisioned Cookbook Left NavBar

• Welcome
• When To Cloud
• Our Cookbooks
  • DAACs
    • NSIDC
    • PO.DAAC
    • OB.DAAC
    • etc.
  • Tools
    • earthaccess
    • [EGIS linked here?]
• Glossary & Cheatsheets
• Cloud Environment Setup
• NEW - Quickstart
• How do I…
  • access data in cloud
    • with ImageServer (How to access EGIS data from an image server)
• Tutorials
  • Add some grouping - one more level of hierarchy - when necessary
    • Add EGIS sub-menu
• Deep dive … (a reorganization of “Tutorials”)
  • by discipline
    • ocean science
      • landing page would have multiple tiles with tags/metadata
    • etc…
  • by satellite
• Workshops & Hackathons
• Access & Administration (remove from nav and make URLs redirect?)
• In Development (move under contributing?
• Contributing
  • In Development
  • Governance (decision docs)
• Appendix (redistribute content to “Glossary”, “Our Cookbooks”, and …?)

I think ideally all the notebooks would fit under "How To's" (How do I...) and "Tutorials". We could try to organize the tutorials by "sphere" (biosphere, hydrosphere, cryosphere, geosphere, atmosphere) if the mentors think that's a good approach.

The notebooks in external/ I think should probably stay where they are and linked to from how-tos/ and tutorials/ since we need to keep track of the notebooks that are sourced from elsewhere. The notebooks in examples/ I think should be moved (after being assessed that are still relevant) to one of how-tos/ and tutorials/.

There has been talk of tagging and having multiple ways of navigating (e.g., by mission, by product, by topic, by library etc.). I'm not sure how feasible that is, unless we set it up using Quarto's blog structure where tagging is front and centre. Otherwise I don't know if tags work in the normal Quarto website structure. Perhaps the next best thing is to lean into search more.

[itcarroll]

Just a little help/interpretation since I think I was partly responsible for taking notes on the proposed navbar/outline above.

1. The "Tutorials" and "Deep dive" bullets are the same, we were just brainstorming what the second (third?) level of navigation should be. Happy with everything being either a how-to or tutorial, as per diátaxis.fr.
2. The "NEW - Quickstart" I think was meant to be oriented toward a users first time doing "in-region" access on NASA Openscapes Hub. Something to tied us over until the full "Cloud Environment Setup" is useable.
3. It's also been proposed that "In Development" notebooks be fully hidden as PRs ... maybe we could have some status table under Contributing though to direct contributors towards them.

[ronnyhdez]

A simple idea I think would be useful, is to group everything in sections, instead of having some "individual" contents such as glossary and cheat sheets or when to cloud in the middle of the sections.

I think all files can be grouped in general sections (and probably in that order) as the following:

• Getting started
• Tutorials
• How-to guides
• Examples by data provider
• External? -> there is a folder named external and the files are in several sections
• Reference (More like appendix)
• Community and Resources (onboarding, contributing etc)
• Administration (the files in access-admin)

I'll draft a PR with this TOC suggestion so we can review how it looks like.

[ronnyhdez]

Just something is making noise in my head: This section. I don't like it at the beginning because I feel that, as an user I just find the cookbook, and one of the first sections is already re-directing me to another website? So I was thinking on putting it at the Community and Resources, but it's a the very bottom, which I'm not sure if it's also a good place.

[jules32]

This is all great Ronny. Let's keep the Our Cookbooks section towards the top for now: this is part of the interconnectedness and vision between Cookbooks that the Mentors are working on right now, in relation to the NASA Earthdata website too :)