Minor improvement of docstring for Dataset

[lumbric]

This might help to avoid confusion. data_vars is always a mapping, not a
mapping, a variable or a tuple.

Passing just a tuple, does not work of course. But for xarray newbies, this might be less obvious and the error message is also not easy to interpret:

>>> xr.Dataset(('dim1', np.ones(5)))
...
TypeError: unhashable type: 'numpy.ndarray'

The correct version of the example above should be:

>>> xr.Dataset({'myvar': ('dim1', np.ones(5))})                                                                            
<xarray.Dataset>
Dimensions:  (dim1: 5)
Dimensions without coordinates: dim1
Data variables:
    myvar    (dim1) float64 1.0 1.0 1.0 1.0 1.0

[max-sixty]

These are great! Agree on the sentence construction.

Any others are welcome, and please feel free to add an entry & attribution in the whats-new at some point

[max-sixty]

(agree on the error message, I think we could do a better job there. We already made some minor changes around sets but we could make broader checks for these initial entry points that new users first encounter)

[lumbric]

Hm yes, good error messages would be great, but I feel like it is widely accepted that in the scientific Python ecosystem error messages are hard to read quite often. Maybe this is the downside the duck typing? I've mentioned this only as explanation why I was so confused after running xr.Dataset for the first time.

[max-sixty]

I feel like it is widely accepted that in the scientific Python ecosystem error messages are hard to read quite often. Maybe this is the downside the duck typing?

We can make it better!
While duck typing does allow passing incorrectly typed arguments, it doesn't prevent us from checking their types. Python now has types like Mapping or Sized which can be used more like protocols and so don't give up flexibility.
So I think it would be strictly dominant for us to check for an instance of Mapping there, and raise a readable error message if it fails.

[lumbric]

Ah yes, true! I've confused something here. dict() accepts mappings, but not everything dict() accepts is a mapping. xr.Dataset() actually accepts only mappings. That makes actually things a bit easier and much clearer.

[shoyer]

Thanks @lumbric !

Feel free to work on improved error messages in another PR :)