Better documentation can make it easier to get started

[danmoseley]

Hypothesis

If it's too hard to get started, newcomers leave the repo -- and documentation is key to preventing that.

Experiment

Ask volunteers to document their first experience with 3 repos unfamiliar with them: dotnet/runtime, dotnet/docs, dotnet/aspnetcore

Success criteria

[BillWagner]

Some details on the headings, based on our groups' discussion:

Hypothesis

We believe that our readme.md and other "get started" docs rely too heavily on shared experiences among team members. Employee team members get help onboarding, get questions answered quickly, and become productive. The crucial information in those sessions don't get added to the "get started" docs. We believe people interested in contributing become discouraged by the onboarding experience.

Success criteria

We'll take the responses from the volunteers to validate or invalidate our hypothesis about that first experience. If we are correct that the onboarding experience is discouraging, we'll incorporate what we've learned to improve those resources. We can re-run the experiment for comparison, and simultaneously measure any changes in contributions from newcomers on the three repos.

[danmoseley]

Jinu update -- doc repository was missing a getting started, now in progress. Looking for volunteers to pilot that readme in the doc repo and evaluate how much it helped.

[BillWagner]

@richlander, @jinujoseph and I met today. The three repos we're working on provide us three different scenarios for this experiment:

• dotnet/runtime has code for libraries. We can assume a new contributor came here knowing they want to update code in the runtime library.
• dotnet/docs has the conceptual docs for .NET. This has a different build and validation system than code, and all the source is markdown. It's a different environment than our code repos.
• dotnet/core has the roadmap for the product, and instructions on finding different repos that are part of the product.

The rest of our discussion focused on dotnet/core.

• The contribute text links to instructions in the runtime repo. This may send new contributors to the wrong place, if they are interested in contributing to a different repo. However, there's a goal of only writing the overall process for contributing once, rather than copied in each repo.
• The link for "up for grabs" issues also only includes the issues in the runtime repo.

We developed the following plan to surface all the "up for grabs" issues across the dotnet org repos:

We'll add a project in the dotnet/core repo for all "up for grabs" issues. The TODO column will have all up for grabs issues across all participating repos.

We can leverage a tool written for dotnet/docs by @adegeo that adds issues to a project when a label is added. The labeler runs as a GitHub action, and is triggered when an issue is opened, closed, or has labels added or removed. (Adding existing issues could be a bit trickier).

[danmoseley]

@jinujoseph is proposing what we can do better in these three repos. Checking that all these repos expose issues to https://up-for-grabs.net so that folks coming into dotnet/core can find places they can contribute.

Plan to experiment with bot to create one single project board.