Description
Documentation Link
https://matplotlib.org/devdocs/devel/index.html
Problem
#26086 puts in a new landing page to make contributing information more discoverable, but is relying on a lot of hand tweaking of links because the contribution docs have a lot of repetition and information at sometimes random seeming level and inconsistency about the scope of the page/section.
Suggested improvement
The docs should be reorganized + consolidated so that that page can pull from tocs. I think the top level bins on that page are the standard stages of contribution, as described by @rcomer #26086 (comment)
- contribute: what can I contribute and help! I'm lost
- setup how do I setup my environment? how do i make a pull request?
- policies: I've written something, what rules do these folks have for what it needs to look like?
To match this structure, I think it's gonna require the following:
- rewrite the specific contributions sections (.i.e. doc, code) in contribute so that they're all "what is this" type intro, as currently code is a deep dive into workflow while docs is super vague, or link out to the specific docs that start with that level of intro and make this doc super meta "i want to contribute & here are the non-type specific basics" DOC: reorganizing contributing docs to clean up toc, better separate topics #27265
- moved minimum dependencies to maintenance section #26218
- clean up dependencies/make them clearer [Doc]: Be more explicit about development dependencies #23831
- figure out what we want to do about the workflow - streamline or gut:
- I've been biased towards we document anything we specifically check for. Also possibly pull in the pull-request non contribution type stuff first section or two of the coding guidelines xref: [Doc]: gitwash deleting main branch #25857
- [Doc]: consolidate coding guidelines #26095
- [Doc]: Sort out doc mechanics/formatting/content guides #26392
- consolidate/streamline triage guidance (this is also spread across a few places)
- adding saved replies to development guide, under triage #23109
- separate out team from mechanics of triage
- next steps in DOC: consolidated coding guide and added naming conventions table #27213
- figure out what we want to do with MEPs - will a contributor ever have to write one or are they historical artifacts?
My preference for consolidation is actually to make folders under devel for at least code and doc (and probably triage) and make a bunch of smaller files for each of the standalone topics & then write a doc against that in an index file that then populates each box. Mostly cause I think it's easier to find docs when developing when they're standalone and not subsections of larger docs.
xref: #22866