matplotlib-devel Mailing List for matplotlib

Documentation is critical for helping people use mpl effectively (or at 
all). Our core documentation has many shortcomings, and needs much more 
attention than it gets. But that's another topic.
This message is prompted by 
https://github.com/matplotlib/matplotlib/pull/3088, which has led to the 
suggestion that we make a separate repo for documenting examples that 
might be too elaborate or specialized to go in the core, but that can be 
more visible, more effective, and better-maintained if they are kept in 
another repo in our github account. They could then be published 
automatically using readthedocs.org.
The primary alternatives here are:
1) Continue with PR 3088 as-is, and encourage other such additions to 
the core docs.
2) Redirect such contributions to http://wiki.scipy.org/Cookbook/Matplotlib.
3) Start a new repo on our github account, as suggested above.
The advantage of (1) is that it keeps everything together; the 
disadvantage is that it makes the central mpl repo even more sprawling 
and harder to coordinate for releases.
The advantage of (2) is that it already exists, and its wiki interface 
might make contributions and updates easier. The disadvantage is that 
it doesn't seem to get much maintenance, and it's wiki format is not as 
nice as full Sphinx docs.
The advantage of (3) is that it encourages expansion of documentation 
that can proceed independently of the core release schedule, and without 
bloating the core.
With either (2) or (3), our core docs should point to the Cookbook location.
The key to making any of these options work well is participation; we 
need people to keep working on improvements.
Eric