Operation Welcome Contributors

[kytrinyx]

I'd like to make exercism welcoming to new contributors, regardless of skill level.

Exercism is a huge project, and some parts have dependencies, others don't. There are several programming languages involved, and lots and lots of potential for confusion.

OpenHatch has a guide for how to make in-person events as successful as possible, and it appears that most of this applies to this type of open source project as well.

I intend for this issue to be the place to have discussions and figure out what the actual action items are, and then open lots of small issues for each specific action item or improvement.

---

There are three things that I want to happen in terms of open source.

First, I want the codebases to be exemplary. I want people to be able to say "Oh, a lovely {something codebase, JSON API, whatever} you can look at is Exercism".

Second, I want it to be easy to contribute. This is partly related to the first, in that an exemplary code base would be easy to understand, but in addition to this I want to have excellent documentation, use very standard conventions given the language/framework, be easy to get running locally, have gorgeous seed data so that the front-end development is fun, and have excellent triage of issues, including a 'beginner-friendly' or similar tag which would let people with little-to-no open source experience get started easily.
Third, I want people to be encouraged to contribute. I want them to NOT be intimidated. I want them to feel welcome and excited about it.

The exercism.io codebase is about as far from exemplary as it can get, at the moment. It's prototype, it started out as a three-day hack and has had numerous experiments and zero UX design. A lot of people have been helping make it better, and there is hope, but at the moment, it's a right mess.

It is not easy to contribute at the moment. The issues and feature requests are not very well tended, and since the codebases are ridiculously confusing, it is quite difficult to figure out how to even write code or troubleshoot something. Also, because the vision is not actually written down anywhere, nobody really knows how to improve existing features or help out.

[kytrinyx]

In addition to fixing the documentation, I would like to organize the issues better.

What strategies can we use to tag things more usefully? How can we better handle high-level discussions?

For existing issues, we can do a much better job of clarifying:

• which skills and concepts are needed
• what is the action item
• where in the codebase can the change be made
• how hard/easy/time consuming is it (often a really difficult thing to assess up front)

For bugs, perhaps we should label them bug? and then bug! when they're unverified vs verified. We should have clear reproduction steps. Perhaps a failing test.

[kotp]

Do you have a skeleton of what you want for the README? Perhaps the WIKI would be a good place for this information, anyway. Especially since the wiki can be pulled and kept in the source repository, tools like Gollum help to author locally, and it has its own source control history, as it is a full git repository?

[kytrinyx]

I would like to have it in the README since that is where people look first. I don't yet have a skeleton for the README, I'm just looking at the guide that OpenHatch wrote, and thinking out loud. My guess is we'll probably try a few things out before we get it right.

[prathamesh-sonpatki]

@kytrinyx For bugs that have reproduction steps, we can label them as with reproduction steps and those that don't have reproduction steps or are not well explained with more clarification needed. These 2 labels are used in Rails repo so I am just thinking they can be used here too.

[kytrinyx]

@prathamesh-sonpatki that sounds like a very helpful distinction. I've been using bug? for things that don't have a reproduction step, but your suggestion is more explicit.

[kytrinyx]

I'm going to close this issue, as I think that we've gotten to a basic, reasonable level of documentation.

I have opened an issue specifically about improving how we label and triage issues here: exercism/discussions#20