Add self-directed help section to CONTRIBUTING.md

[jtigger]

Implements exercism/discussions#73.

You'll get the most complete feel following this path:

1. I see a problem...
2. ... with a specific exercise.

The general intent is for someone with not a lot of experience of behind-the-scenes exercism to quickly find the place and information needed to start contributing... whether it's "just" reporting an issue, submitting a fix/enhancement, or even taking on thinking about more strategic things.

This work will be followed by an effort to split this page and related pages into "modules" of units-of-work that will be referred from this "decision tree." (think: a set of .md files under docs, one per workflow).

Brutally honest feedback, please! :)

[kytrinyx]

Holy smokes I really like where this is going. The ability to drill down really quickly is powerful.

I'm wishing I had more brutally useful feedback, but I don't. I think you're on to something here.

[kytrinyx]

FYI we don't actually have any Rails in the project.

[Insti]

I also like what you're doing here.
(But don't have any specific feedback, just keep doing what you're doing?)

[tejasbubane]

These ... seem a little odd and distracting to me. But this is just my opinion.

Can we have full sentences like I see a problem getting started with a language?
Something like this:

[jtigger]

Thanks for your feedback, @tejasbubane! The "motivation" behind the ellipsis (...) was to help convey that the reader going through a flow.

If I understand your suggestion, the headers of each landing section is a complete sentence and there are not ellipsis. Yes?

[tejasbubane]

the headers of each landing section is a complete sentence and there are not ellipsis. Yes?

Yes. Looks better IMO. Lets see what others have to say.

[jtigger]

Ditto. Thanks for the feedback!! If you see think of anything else, big or small, please share!

[kytrinyx]

This is a tangent, and you've likely not even considered the aesthetics of it yet, but I've seen people use octicons and/or fontawesome to good effect.

https://octicons.github.com

• bug: https://octicons.github.com/icon/bug/
• idea: https://octicons.github.com/icon/light-bulb/
• help (?)
  • https://octicons.github.com/icon/gift/
  • https://octicons.github.com/icon/heart/
• website: https://octicons.github.com/icon/browser/
• exercise (?)
  • https://octicons.github.com/icon/keyboard/
  • https://octicons.github.com/icon/file-binary/
• ... etc

[jtigger]

Note, @kytrinyx, I've rebased over your branch to include references to the Contributor guides you've been working on (#3232) — great stuff!

[jtigger]

You're right: I have specifically avoided investing in the graphics part. I'm the LAST guy you want picking graphics. I grabbed some from Google image search that said they were "royalty free".

Re:octicons — very cool!

[jtigger]

At this point, I believe I've reached a milestone with this work and ready to submit for review.

@kytrinyx, I'm specifically deferring doing anything with graphics. I would ❤️ to see someone with graphics design chops give these an Exercism vibe. Far more important seemed to be the contextualizing of someone's intent.

I also followed your advice, @kytrinyx, and created issues for other sections that this guide links to. Those pages point back to their issues, respectively.

Some leaves on this decision tree are stronger than others. I hope by calling this a first iteration of "done", others can start to elaborate/tweak/adjust.

[jtigger]

This is such a significant chunk of work (with sub-parts pending), I'd love to either push this through or course-correct as needed.

@kytrinyx?

[kytrinyx]

@jtigger sorry, I've been traveling non-stop for the past 6 weeks. I'm still traveling, but I'm spending Thanksgiving reviewing PRs and cleaning things up in Exercism, so I'll take a look at this today or tomorrow.

[kytrinyx]

@jtigger this is an awesome first pass.

I saw an its' vs it's but I'm going to let that get fixed in some subsequent pass. Same with the images.

Thank you so much for taking the time to dig so deeply into this.

[ErikSchierboom]

Wonderful improvement! Great work @jtigger

[jtigger]

@kytrinyx I hope I came across as a "squeaky wheel" and not impatient. I'm delighted to get through a first iteration. It's quite imperfect, but I have hope in this approach.

We could really use a designer's eye on this:

• what are the common goals, workflows and attendant ux?
• better graphics!!! and
  perhaps ideals on making the visual design easier on the eyes?

[kytrinyx]

We sure could use a designer's eye!

It feels like there are some different categories of contribution docs:

1. Exercism, the Product
2. Exercism, the Curriculum and Language Tracks
3. GitHub / Workflow / Conventions

And within each of those categories, there are lots of sub-categories.

The thing that is so hard for me to figure out is—where are people starting from? Where are they when they decide to contribute? What do they find first? I have literally not a single clue.

[jtigger]

@kytrinyx

The thing that is so hard for me to figure out is—where are people starting from? Where are they when they decide to contribute? What do they find first? I have literally not a single clue.

EXACTLY! That has been one of the most challenging parts in doing this. I spent most of my time on the PR sitting there trying to imagine what are those inbound paths.

It's really easy to want to speak to our audience in terms that we understand... when it's an order-of-magnitude better experience when we shoulder up with them and speak from their perspective.

One thing that started to become clear to me is that this guide is aiming to help the uninitiated.... once someone starts to wrap their arms around the organization and culture of Exercism, such a guided tour becomes less and less useful — there are richer sources of help in terms of the relationships this person has established. So, the good news is that we don't have to account for all paths, just the common ones that new-to-exercism folks might hit.

I've wanted to contribute when:

• I go through the on boarding process and hit snags.
• I've seen a bug in the website or in the CLI.
• I'm reviewing others' submissions and start wishing for features that optimizes my workflow.
• I'm solving an exercise and find problems with it (usually I'm frustrated with the API spelled out by the tests... but also by the value/path the tests encourage... and then other times the language of the description.md).
• ...