html_url,issue_url,id,node_id,user,created_at,updated_at,author_association,body,reactions,performed_via_github_app,issue
https://github.com/pydata/xarray/issues/3564#issuecomment-565539415,https://api.github.com/repos/pydata/xarray/issues/3564,565539415,MDEyOklzc3VlQ29tbWVudDU2NTUzOTQxNQ==,35968931,2019-12-13T17:50:15Z,2019-12-13T17:50:15Z,MEMBER,"> Maybe there are at least 3 levels in there, actually...

The [article linked](https://www.divio.com/blog/documentation/) by @keewis is well worth reading in my opinion - it describes a similar breakdown of different types of documentation:

- **Tutorials** - learning-oriented lessons to get newcomers started,
- **How-to guides** - goal-oriented series of steps to solve a specific problem,
- **Explanation** -  understanding-oriented discussion providing background and context,
- **Reference** - information-oriented description of technical machinery.

I think for xarray there is another type, like you suggest @choldgraf:

- **Domain use-cases (/inspiration/showing-off)** - showcase-oriented examples of groups using xarray in anger to do something cool.

I personally think xarray in general has **reference** nailed, lots of good **explanation**, but is generally a bit weaker on **tutorials** and **how-to guides**, and doesn't have many examples of **domain use-cases**.

---

I have some ideas for how-to's (maybe these should all go in a separate issue?):

- **How to migrate from numpy to xarray** - Huge numbers of numpy users need to shown exactly what code should be replaced with what, and what they can then stop worrying about.
- **How to apply your own analysis functions** - i.e. `apply_ufunc` how-to. The [existing documentation](http://xarray.pydata.org/en/stable/computation.html#wrapping-custom-computation) on that is more along the lines of an explanation in my opinion, and I've certainly found `apply_ufunc` to have a steep learning curve. 
- **How to organise domain-specific functionality** - In-depth guide to various tricks you can pull with accessors, and when you might want to go beyond that. The [documentation we have](http://xarray.pydata.org/en/stable/internals.html#extending-xarray) on that only shows a couple of possible approaches.

---

> We need the tutorials to be able to run and build within a CI environment.

So @rabernat for small datasets what might be an appropriate max filesize? I literally have no idea. ~1MB?

> a good approach is to create an archive on https://zenodo.org/

I'll look into that.","{""total_count"": 1, ""+1"": 1, ""-1"": 0, ""laugh"": 0, ""hooray"": 0, ""confused"": 0, ""heart"": 0, ""rocket"": 0, ""eyes"": 0}",,527323165
https://github.com/pydata/xarray/issues/3564#issuecomment-561227888,https://api.github.com/repos/pydata/xarray/issues/3564,561227888,MDEyOklzc3VlQ29tbWVudDU2MTIyNzg4OA==,35968931,2019-12-03T15:48:05Z,2019-12-03T15:48:05Z,MEMBER,"@rabernat I'm going to be making a simple plasma physics-oriented xarray tutorial to give at a workshop next week. 

I was wondering - if we're uploading real data for these, how big can/should the files be? It might affect what dataset I use.","{""total_count"": 0, ""+1"": 0, ""-1"": 0, ""laugh"": 0, ""hooray"": 0, ""confused"": 0, ""heart"": 0, ""rocket"": 0, ""eyes"": 0}",,527323165