Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Quick Start Guide for docs main page[DOC] #268

Open
jbusecke opened this issue Oct 9, 2020 · 5 comments · May be fixed by #271
Open

Quick Start Guide for docs main page[DOC] #268

jbusecke opened this issue Oct 9, 2020 · 5 comments · May be fixed by #271
Labels
docs In Progress Somebody is working on fixing this issue

Comments

@jbusecke
Copy link
Contributor

jbusecke commented Oct 9, 2020

Over the past days, I have had many great conversations with people who have been using xgcm for the first time.

From those exchanges I think that we have an urgent need for a 'quickstart' section in our docs, which perhaps should be on the index page itself.

I am thinking of a short 'recipe' style guide that links to other more detailed parts of the package.

# xgcm docs 

## What is xgcm
A very brief blurb about xgcm and the role of the `Grid` object.

## Quickstart guide

### What do you need to get going with xgcm? (Ingredients)

1. ) A dataset. Any gridded dataset will do.
2. ) Familiarize yourself with the dataset, and figure out the logical `axes`. More info [here]. 
	You don't have multiple dimensions per axis (common for observational gridded datasets)? [Here] is a guide how to reconstruct them.
3. ) Find out what 'metrics' you have available in the dataset (think: distances, areas, volumes), these are optional, but you need to define them if you want to use the more awesome features (like `.integrate`, 'average', etc). 
    - Don't have metrics? [Here] is a guide on how to infer them. 
    - You have some of the metrics but not for all possible grid positions? [Here] is a guide on how to populate the full grid.

### How to set up a grid object (Instructions)

... step by step example

This would address/integrate many issues that came up in the past (e.g. #196 and others).
What do others think about this?
@jbusecke jbusecke added the docs label Oct 9, 2020
@timothyas
Copy link
Contributor

I think this is a great idea @jbusecke! And I think the step by step example for setting up a grid can be a very simple, quick example, with again links to the more detailed pages in the docs (like setting up the LLC grid, for example).

@jbusecke
Copy link
Contributor Author

jbusecke commented Oct 9, 2020

Exactly, just an idea about what step has to be done when.

@Thomas-Moore-Creative
Copy link

@jbusecke , I reckon this would definitely widen the adoption of xgcm and broaden the community.

I'm not sure what you and your team think but I'd propose the audience should be as wide as folks who are a few steps removed from running a GCM and have just downloaded some "model variables" from some remote source?

These folks might not be aware of how to get the more detailed grid information & metrics or if they are even available. (side note: maybe xgcm could provide guiding "better practice" for those who run models as to what they should choose to output with the diagnostic variables? My limited experience is that when model output is made "public" it's not always clear?)

As someone digging through the entrails of some specific modelling systems I'm happy to provide documentation & help with examples that might feed into #258?

One use case that I think is common and that might be great to have in the "quickstart" guide is "xgcm use for regional subsets of a model", for example simple 2D or 3D averages of tracer fields? As you've mentioned in places ( #193 ) current recommended practice is to create a new grid after subsetting the data. An example might help clarify especially since not following this practice gives a result that is wrong but might not be obviously so?

@rcaneill
Copy link
Contributor

I can give my personal feedback on when I discovered xgcm a little bit more than one year ago. Many things have changed since then (more doc, automatic using of metrics, etc), and that's awesome!
However, coming from the NEMO community and with no experience of the MITgcm nomenclature (XC, XG, dxC, etc), with no-one around me knowing xgcm, it took me a while to understand how to use xgcm properly. So my humble opinion would be that this quick start guide should be as wide as possible, avoiding to use model specific names (like done in the "Simple grids" page). This would have helped me at the beginning, I think (however, due to the expanding of the examples for different model outputs, my comment is maybe outdated).

@jbusecke jbusecke mentioned this issue Oct 12, 2020
Open
@jbusecke
Copy link
Contributor Author

Thanks @rcaneill ,

I think this is very much aligned with what I had in mind. Let me try to get a draft together later today. If you have time, I would greatly appreciate your feedback on that!

@jbusecke jbusecke added the In Progress Somebody is working on fixing this issue label Oct 12, 2020
@jbusecke jbusecke linked a pull request Oct 13, 2020 that will close this issue
Open
4 tasks
@rcaneill rcaneill mentioned this issue Mar 30, 2022
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
docs In Progress Somebody is working on fixing this issue
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

WIP: Quickstart Guide for the docs jbusecke/xgcm
4 participants
@jbusecke @rcaneill @timothyas @Thomas-Moore-Creative