issue_comments: 565539415

This data as json

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 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 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 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