Contributor onboarding & retention

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

Particularly interested in how https://matplotlib.org/devel/index.html# can be improved & what sort of info & support folk would find valuable.

Edit to eek: https://matplotlib.org/devdocs/devel/index.html is the right landing page for new contributors & that it’s not the default is also a problem.

1 Like

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:

  1. If I come to page not knowing what I want does it help me find the right page?
  2. 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:

  1. 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

  2. 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
  3. 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.

  1. Write a general codebase orientation. It took me a while to figure out where things actually live. Even something as simple as what jupyterlab has could go a long way: https://jupyterlab.readthedocs.io/en/stable/developer/repo.html#
    • I also really like the jlab dev docs, I think emulating the organization and presentation style would be be a good approach.
  2. Create a concrete example of how to contribute (maybe a youtube video showing the entire process?)
1 Like

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).

(This is basically ripped from https://mpl-interactions.readthedocs.io/en/stable/Contributing.html, and is almost certainly excessively verbose - concision is not a word often associated with my writing unfortunately :cry: )

Totally agree w/ you on the onboarding page being :weary: 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.

1 Like