Add additional contributing guidelines to contributing.md

[joedolson]

We should establish guidelines for the contribution process. One guideline I specifically think we should consider is a requirement to create an issue before creating a pull request. This is specifically to make it easier to manage multiple solutions to a problem and to be able to own issues.

[zzap]

At yesterday's meeting, I asked whether we want just anyone to be able to assign themselves to the issue, or if we want to keep it as is (only if you are added to the org, or someone else assigns you), because that will affect the docs for contributing. And the answer is to keep it as is, in order to avoid random contributions and potentially create more work for active contributors. This model is to be replicated in every other FAIR repo as long as possible, to maintain consistency.

So, I got a semi-evil idea about this.

A few years ago, I was trying to promote the idea of paired team members in a WordPress project. A core developer would get assigned a documentor, who would "shadow" the work on PR; ask questions about the feature, follow the whole process of developing and making decisions and iterations, AND document all of it. By the time feature gets into the core, complete documentation (dev note, inline docs, reference, etc.) would be ready, the documentor would be one step closer to do the code contribution "the WordPress way", and the developer would understand more how documenting code works (as their most common argument is that they don't know how to write the docs).

Now, when I started proposing it, it sounded like a great idea to everyone, but no one wanted to do it. And, granted, it's very difficult to start implementing such a workflow in a project that is so big, has no solution for onboarding, and is welcoming random contributions.

However, this project seems to be just the right age and size for it. It exists long enough to have a small group of dedicated contributors, but this group is small enough to barely keep up with upcoming challenges. The project is promising to be big enough so that no one person can keep it in their head for much longer, which begs for proper documentation on both how things work and how to work on things.

This is the moment when the "bewitched circle" starts forming, and things can become extremely frustrating. What is the bewitched circle, you ask?

---
title: The bewitched circle
---
flowchart TB
    A[["The project gets bigger"]] --> 
    B["you need more contributors"]-->
    C{"contributors come and ask how they can help"}
    C-- ONBOARDING -->D["you don't have a time to show them how"]-->D1[\"part of contributors leave"/]
    C-- DOCUMENTATION-->E["you don't have any docs because you didn't have time to write it"]-->D1
    D-->D2["the other part tries to figure out things"]-- BUT -->F((("project is already too complex for random figuring out")))
    E-->D2
    F-->F1["quality of contributions is very low"]-- which -->F2["requires more people to triage and fix"]-->B

Loading

Since we don't want those random contributions, simply for the economics of the time and quality, and keeping in mind two fundamental reasons people join the open-source projects (1. doing something meaningful where they, 2. feel they are benefiting in skills, knowledge, etc.), I am proposing the following:

Let's make the onboarding (as the highest priority) an opportunity for writing the docs, establishing the specific "FAIR workflows", while building a high-quality reputation for both the project and its contributors.

In practice

A new contributor (for writing the code), must spend one month or 3 PRs in an onboarding process. This process consists of them working closely with an active contributor on their current PRs. A potential new contributor will have a set of tasks:

• writing/updating onboarding docs,
• writing docs for the feature in PR (hence working closely with the developer)
• preparing the docs for the PR

By the end of this month, or 3 PRs (with the same or different active contributors), the new contributor should gain deeper insights into what this specific repo is about and how to keep contributing to it. Furthermore, this contributor will know exactly how to contribute to other repos in the project (consistency). They will also feel like their contributions matter because someone actively dedicated time to them, which will increase the chances for them to stay and keep contributing. The workflows of parallel documenting and developing will settle in and become the default, which will increase the project's longevity and health by 80% (I will die on this hill).

Over time, FAIR will become a project known for "breeding" quality code, good developers who also do the docs, with exceptional contributor experience.

cc @courtneyr-dev

[toderash]

@zzap you're a genius. First thought was we don't have enough people for this, but I think we probably do - they just don't know how to contribute yet. cc @mgratch wrt onboarding and @cdils - I think we need a "GitHub Bootcamp for Non-Developers" to help get this going. I'm good with using GH for {all-the-reasons} but non-developer writers will find it cryptic and daunting.

[zzap]

@toderash, different doc types require different skills, and we can honour this and refine specific workflows. Also, the best documentation is written by people who are using it (I will die on this hill as well), so the tools should be adjusted to accommodate the user group as well. But tooling is another discussion, for which discovery is in progress with Courtney's document in slack.