I agree with those changes. One thing I have though about though and I was about to write about in the discussion. I have no problem if this get merge directly though.

I believe that the matplotlib in for example ~matplotlib.axes.Axescould be left out most of the times. It makes the string longer without given much information for most users.

I believe that it often make sense to include the module name also in the rendered documentation. Some docstrings, like for the colorbar module, looks strange when it is rendered as colorbar is a thin wrapper of colorbar. It would be easer to read as pyplot.colorbar is a thin wrapper of Figure.colorbar.

I believe that I in most cases want to read the module name also in the rendered documentation.

That looks good to me (although I am worried about the length of the document. Those are typically never read by our contributors, including core-contributors)

Even if not everyone follows those guidelines exactly, it's still of value. It can be seen as an aspirational goal, and if we follow at least partly we're still converging in that direction. Actually, there have been requests for a better documentation guide. After all, it can help a contributor to find out how to do certain things. We have a lot of different styles in the actual docs, because the guidelines have changed over time. Having an up-to-date document to reference when in doubt is a good thing. This is essentially a collection of proven best practices.

The length can actually be a bit daunting. I've tried to cut back on duplication, give it more structure and add examples, so that one can find out certain aspects without having to read the complete document. It's still far from perfect. There can be done more to clean up the guidelines, but it's a step in the right direction.

@timhoffm I agree with all of what you say :) It's just typically easier when all of the documentation follows the same convention already. That's the challenge with an 18year-old project, that predates most of the modern documentation tools and documentation.

I'd like this to be reviewed by another core developer before the document being merged, as this clarifies some conventions, and we ideally all should be in sync on that.

If we don't get another review on this soon, I'll just go ahead and merge it.

Ok, this looks great. Thanks @choldgraf for the review (despite the bad timing 😄 ) and thanks @timhoffm for updating the docs on writing docs!

Backporting this to v2.2.x to fix CI issues there

@meeseeksdev backport to v2.2.x