How to make things simpler/clearer for users?

[dougiesquire]

This issue is to suggest and discuss ways to make things easier for catalog users.

cc @headmetal, @svenbuder

Tasks to do, based on comments in this issue:

• reorganise documentation - see comment, addressed in Overhaul of the documentation #81
• update language in tutorials to be clearer - see comment, addressed in Overhaul of the documentation #81
• clarify example_usage.ipynb - see comment, addressed in Overhaul of the documentation #81

[dougiesquire]

The docs need work - see #59

[dougiesquire]

In example notebooks, variables could be renamed to be more explicit about what they are, e.g.

• metacat -> catalog
• subcat -> esm_datastore

ACCESS-NRI will definitely need to provide training on intake-esm as part of any training on our catalog

[dougiesquire]

From @headmetal:

In cell 11 of example_usage.ipynb, the implication is that the filename query is searching on the keys shown in the previous cell, which is not correct.

We should change the search to:

subcat2 = subcat.search(variable="temp_global_ave")

which returns the same datasets.

[marc-white]

@rbeucher @charles-turner-1 and I bought some related issues up around this in a meeting yesterday - should we hijack this issue to cover them off? (Romain mentioned there might have been some similar issues raised by @pboubel )

[marc-white]

Also found this issue in the back-catalog that ties in nicely here: #26