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