Improving tutorials for v1.6 (proposed roadmap: tags)

[bearecinos]

Hi everyone,

@ehultee, @suther11LBU and I, did a bit of gathering of thoughts on the tutorials (among other things) that we have encountered, I will try my best to summarise things in different issues. This issue being the most general one (more issues will come to document a road map in the different repositories).

General comments

We feel the tutorials ATM need to be organised in order to find quickly the information. We are sure that many things that we need are already there, but it does take a while for experienced users (like myself) to find stuff so it is not straight forward for undergrads. I propose (before suggesting new tutorials) .. that we make an organisation of existing tutorials and information.

Specific issues:

• The current classification (beginners + advance & 10 mins to ...) its good, but maybe not as useful to find what you want. We were thinking we could add more categories or subcategories (short headlines at another page on the tutorials website, or an organization chart of tutorials, index, etc)

  Possible solution: @ehultee: suggested to add hyperlinked “tags”? My vision is that a tag would appear on every tutorial it applies to, and if you click on a tag you can see the other tutorials that have it? Then the tags would be the categories you list below.

  Tags example (though we can probably think of better ones): - OGGM shop - Glacier initial state - Glacier evolution - Calibration - Education! (see last point) - etc

• We could link each model task (info section) in docs.oggm.org with a tutorial & tag this would enhance the docs.oggm.org sections by adding a tutorial to each part of the docs workflow.

@ehultee: Edu material (apps, helper functions, etc) has become more abstract and slick, and core OGGM has become more technical. There is a missing middle. As a result, these resources do not work well together in the same educational setting. I taught students starting with edu notebooks, and it was a huge leap for them to understand what the real OGGM workflow was doing. I ended up doing a lot of troubleshooting for them when they worked with core OGGM.

• Maybe there needs to be an “education” tag (on the tutorial tags I suggested above) to clarify what is aiming to help students/educators, and what is intended as a “live documentation” for research users? For example, the advanced MB calibration tutorial is likely not intended for students...

[fmaussion]

Thanks for these comments. I finally found time to read and process them carefully and I agree with all of them.

They seems solvable relatively easily:

• I will look into the tagged hyperlinks - I'm confident there should be a solution to this, it will require some organisation
• yes to the "issue" with the new OGGM-Edu library. Its purpose was always to hide the core OGGM workflow and ease the introduction of students to programming. It strongly limits what can be done with OGGM itself, I agree. I don't think I want to go back to where we were, but we need more beginner tutorials in OGGM itself now.

[fmaussion]

I don't think that such tags exist as of now, but I asked online: https://github.com/orgs/executablebooks/discussions/1128

With a little of book-keeping we could do our own structure by tag though.

[fmaussion]

I've tried something new here: https://oggm.org/tutorials/master/notebooks/welcome.html

I stopped the ordering between "beginner" and "advanced" which was very subjective anyways. I tried to order the notebooks via "themes". It's only a first step, perhaps we can work towards a better documentation over the next few weeks?

[bearecinos]

Hi, this looks way better! Happy to help organize on the next week!