larsoner
commented
1 year ago Works for me. One way to think of beginner vs advanced topics/pages might be to target the beginner one toward someone who quickly wants to make a one or two line fix, and not concentrating on telling them everything but just enough that they might get it right on the first try. If there is too much text people won't read it, so I think it's better to be brief but incomplete and hit on the most important points. To me that's: using a GitHub workflow, TDD, and adding changes to the change log. FWIW this is what I have to comment on in beginner contributor reviews most of the time. The rest (like style issues) CIs help with and people often self correct in-PR.
Then at the end of the beginner doc we could write "some problem with your PR? See the advanced page!" And there in advanced we talk about flake, Makefile, html_dev-noplot, etc.
britta-wstnr
drammock
In the last dev meeting, @drammock and I discussed that our Contributing Guide may need an overhaul.
Right now, the guide is long, hard to navigate if you search for something, and hard to understand/follow for new contributors.
The topics discussed (in order) within one page are right now: ways to contribute, configuring git, GNU make explanation, forking and upstream on GitHub, virtual environments, git commands, SSH with GitHub, documentation, API changes, changelog, local testing, test writing, coding style, naming conventions, docstrings, cross-referencing, code organization, testing, building documentation, MNE command-line tools, GitHub workflow.
While undoubtedly all of this is important, the info is overwhelming and switches between topics (which might make sense, again, if you are following while contributing, but it might be hard to connect the dots when reading this for the first time).
I propose to chop this up into several pages (make it feel less overwhelming, have information on one topic more bundled and use links to interconnect). Further, I propose to potentially have different versions for new contributors and advanced contributors. This could e.g. be realized by having bullet point summaries at the top (if you just need to read up on something you forgot) and then more detailed explanations further down.
TL;DR: Proposal to split the contributor guide into several pages and have sections that speak to the advanced contributor that just wants to look something up as well as sections that are easier to follow and give detailed explanation.