So we’re rethinking/revamping our contributing process and we wanna know what isn’t working. What’s keeping you from contributing or sticking around? Drop your thoughts in this thread or privately at https://forms.gle/Ud7eFvsNmF8anpAu8
Looking through https://matplotlib.org/devel/index.html# I mostly feel overwhelmed. I think this is because there is a lot complexity that is covered. Much of this is intrinsic because matplotlib is a complex project, but the structure it is presented in could be revamped to be much more readable/scannable.
Maybe two metrics for success here are:
If I come to page not knowing what I want does it help me find the right page?
If I want to set up dev install and make a PR with bug fix: Is it easily scannable such that I can find the directions for this in <30 seconds and under 2-3 clicks?
Currently the answer to both of these is no.
Concrete suggestions:
Add some text at the top of the page that is welcoming and (in prose) directs the reader to links for various things that they might want. Also link to gitter + discourse as places for help
Reconsider the indentation levels of various topics. For exampleCurrently an explanation of .. vs ... in git is at the same indentation level as setting up a development env. This makes it much more difficult to scan for the relevant sections
sub point: reduce/remove the lengthy explanations of git. Direct readers to a dedicated external guide. Possibly push a GUI such as github desktop
ReOrder the top level headings. I think that the three subheadings in Contributing should really be the first three major headings:
Contributing code
Contributing documentation
Other ways to contribute
then other sections could subsumed into them e.g. tips for testing should live under contributing code.
After posting that I realized that I really want to emphasize point 1. It’s a super bummer to click the contributing tab and just be presented with a huge table on contents.
As a start:
Thanks for thinking of a way to help improve matplotlib! Remember that contributions come in all shapes and sizes beyond writing bug fixes. Contributing to documentation, opening new issues for bugs, asking for clarification on things you find unclear, and requesting new features, are all super valuable contributions. If you have any questions on the process or how to fix something feel free to ask on gitter(make this a link) or discourse (link).
Totally agree w/ you on the onboarding page being and realizing a potential really really easy fix is remove a level or three of headings 'cause the person hitting this page probably needs to read all of the subheading stuff anyway-pull out install into it’s own heading too.
Also agree w/ you on codebase orientation - my GSOC took like a month to sort out where things live & I had Tom and Mike as mentors…
Would you be interested in contributing a youtube video/twitch stream/tiktok on how to contribute?
I can’t imagine there being any objection to someone spending some time re-organizing and editing. Its clear that page evolved organically, and the information is pretty ad-hoc. Much of the info could be linked elsewhere. Plus there are lots of projects who have written their own onboarding docs that could be used for inspiration and ideas.
@ianhi, if you or someone else are interested in taking this on, I’m sure the community would be very excited to help.