netCDF reading is not prominent in the docs

[rabernat]

Just opening an issue to highlight what I think is a problem with the docs.

For me, the primary use of xarray is to read and process existing netCDF data files. @shoyer's popular blog post illustrates this use case extremely well.

However, when I open the docs, I have to dig quite deep before I can see how to read a netCDF file. This could be turning away many potential users. The stuff about netCDF reading is hidden under "Serialization and IO". Many potential users will have no idea what either of these words mean.

IMO the solution to this is to reorganize the docs to make reading netCDF much more prominent and obvious.

[shoyer]

The challenge here is that xarray has two big audiences (netCDF users and non-netCDF users), for which the right approach is very different. I tried to avoid being too netCDF specific in the docs to avoid turning off folks who aren't familiar with it. This is not to say that they would not appreciate learning more about netCDF, but I know that an overemphasis on domain specific file formats can quickly turn people off.

So we almost need two separate introduction/tutorial pages, one for people who know netCDF and one for people who don't.

[fmaussion]

See also: #768 (comment)

He wrote:

Looking back, I actually think the documentation could use some work to help people like me, who haven't used netcdf, realize it's great.

[shoyer]

@fmaussion yes, that's a really good point -- the intro for users who don't know netCDF should end with a call to arms about how great netCDF is :).

[rabernat]

@shoyer I definitely see your point!

[fmaussion]

Partly addressed via #1169

I'll leave the issue opened in case someone wants to add a more comprehensive netCDF doc later on

[stale]

In order to maintain a list of currently relevant issues, we mark issues as stale after a period of inactivity
If this issue remains relevant, please comment here; otherwise it will be marked as closed automatically

[jhamman]

Closing based on the recent documentation updates (e.g. #2430) and older PRs like #1169.