Brier Score - References in API & Tutorial

[Steph-Chong]

The reference in the Brier Score API is for the Wikipedia page: https://en.wikipedia.org/wiki/Brier_score.

The reference in the tutorial and included.md is Brier (1950), for which the DOI is - https://doi.org/10.1175/1520-0493(1950)078%3C0001:VOFEIT%3E2.0.CO;2

1. API: Should the Brier Score API list both the Wikipedia page and Brier (1950) references?
2. Tutorial: The Brier Score reference in the tutorial is hyperlinked to a citeseerx version of the article. I have sometimes come across citeseerx URLs that stop resolving. There is a DOI (listed above, and linked to in included.md) for Brier (1950) - which includes a freely available, full text PDF version of the article. I think it would be better to change the link in the tutorial to the DOI.
3. Tutorial: If anybody is worried people will have trouble finding the full text PDF at the DOI, you could include a note saying to click one of the PDF buttons

[tennlee]

(1) The wikipedia entry is much more accessible to quickly get across the score. We could do with a consistent "spec" for the docstrings which will generally answer what should be in there. My feeling is that we should have both references in the API docstring.

(2) Yes, this should be changed to the DOI.

(3). I'm not worried about that, it seemed quite clear how to access the PDF, but if anyone disagrees please say so.

@Steph-Chong I'd be interested in your take on point 1. I'm happy to go ahead and make the change, but I wonder if I should create an issue for putting together a "spec" or template reference for the docstrings and we can then move towards a standard approach to the sections of docstrings.

[Steph-Chong]

I think a spec for docstrings would be great (it is actually something I had been thinking about).

We've refined our approach to docstrings over time, and I think they have gotten better as a result. But it does mean the docstrings in the API are currently a bit inconsistent.

I think a spec would (a) be useful for new contributors and (b) over time we could (where necessary) update existing docstrings to match.

I think it is probably worth adding it to the pull request checklist - as contributors should be looking at that as part of making a PR. It could additionally be added to the contributing guide (but that document is already very long).