Overhaul contributing documentation

[kytrinyx]

I'd like to reorganize the documentation to make it easier for people to find what they are looking for.

The basic idea is to center each bit of documentation around workflow. People tend to be trying to achieve something specific when they're contributing, and I think that having separate documents for different goals make sense.

We've started doing this in https://github.com/exercism/x-common/blob/master/CONTRIBUTING.md but it's a massive wall of text, which is overwhelming.

e.g.

• how to review a pull request
• how to add a new exercise
• how to fix a typo in an exercise README
• how to set up a local development environment

The CONTRIBUTING guide would be a point of entry that would have short paragraphs that lead people towards the documentation that they're looking for.

Here are a couple of projects that do documentation really well:

• Jekyll: https://github.com/jekyll/jekyll/blob/master/docs/reviewing-a-pull-request.md
• Homebrew: https://github.com/Homebrew/brew/blob/master/docs/Maintainers-Avoiding-Burnout.md
• Hoodie: https://github.com/hoodiehq/hoodie/blob/master/TRIAGING.md

Here's a resource from Mozilla on the topic: http://mozillascience.github.io/working-open-workshop

[jtigger]

(fixed broken link to the Homebrew "Maintainers Avoiding Burnout" page)

[kytrinyx]

Thanks @jtigger!

I made a start at maintainer docs:

• Maintaining a Track
• Reviewing a Pull Request

[jtigger]

I am attempting to map out the flow for a contributor both from the top-down and the bottom-up.

Top-down means something like this:

1. A person sees/feels a need
2. Clicks on a (more) visible "Contribute" link/button to get to the "Contribute to Exercism" page
3. Greeted with a top-level triage:
   
4. Each of which breaks it down one more level...
   
5. Which draws together links to "modules" of information, specific workflows, along with potentially task-specific steps:
   

... the simplest way I can think of implementing this is where each step is a single page... it would feel somewhat wizard-like as they navigate through the tree.

There's a whole 'nother part of this (the "bottom-up" aspect I alluded to, above) which is about figuring out what those "modules" (think common sets of steps like "How to create a Pull Request", "How to add a new exercise"... most of which actually exist, just organizing that information into composable chunks) are.

Thoughts?

[troubalex]

I like your thinking, @jtigger! In content strategy, there is the concept of structuring content based on chunks or modules. By mapping out a potential flow, it should be possible to identify and define chunks of content that are relevant at each step of the journey.

Once that is clear, it should also become quite obvious which chunks should be reused in different context, and how potential pages should be grouped, and how their content should best be structured.

That way, you don't have to make any implementation decisions before you know which pieces of information are needed. I suspect, the result is going to be closer to a well-organized page-stack than to a wizard, but there is no way of knowing before you break out the sticky notes.

[jtigger]

Brilliant suggestion, @troubalex; thank you. I will do exactly that.

I know there are some online stickie apps; I'll do some work there and report back.

[troubalex]

Let me know if you find a good tool. Alternatively, you could use real sticky notes, and transfer you results into a spreadsheet where you use one row per task. Subtasks can be indented.

[kytrinyx]

I like this a lot!

Sort of related: I did a rewrite in the README a couple weeks ago, and started trying to address the top-down thingy: https://github.com/exercism/exercism.io#contributing-to-exercism

[jtigger]

@kytrinyx oh, I know it! I'm doing everything I can to digest and incorporate "prior art." My attitude is that there's tons of great material and what's needed is in increase in discoverability. Sure there may be some gaps, but from what I've read, there's lot of well-written material already.

[jtigger]

Working out in the open: https://docs.google.com/drawings/d/1kE7VqIBMj4gj5702a_LDaOkkvKQ1dJsaapzeuIEC5Lw/edit

[jtigger]

Starting a backlog around this here: https://github.com/exercism/exercism.io/projects/1

My plan is to

1. put in single-sentence cards to seed.
2. invalidate some (already done?), rework others
3. convert into issues
4. get to work!

[jtigger]

@kytrinyx I was thinking, at first, that the starting point would be http://exercism.io/contribute ... however, I notice that when I go to create a new issue, I see this handy prompt:

Which links to https://github.com/exercism/exercism.io/blob/master/CONTRIBUTING.md. This means that page is also going to be a likely first step in the UX flow.

What do you think of the idea of having the link in the footer of the website point directly to the CONTRIBUTING.md file in the repo? ... and that file be the starting point of flow?

[kytrinyx]

What do you think of the idea of having the link in the footer of the website point directly to the CONTRIBUTING.md file in the repo? ... and that file be the starting point of flow?

Yeah, I think that would be a good idea. It doesn't really help to throw them directly in the issues.

[jtigger]

Cool. So, the current revision of the "Contribute" page on the website has triaging right now. We should hold off on changing that link until at least a first iteration (thinking of MVP as at least covering all the topics represented on that page).

[kytrinyx]

I think we're good to go now to change the link in the footer of the page, right @jtigger?

[jtigger]

That's right. Two tasks left on this one part: exercism/exercism#3187. Then it's considered "done" (first iteration caveats). I'm tracking "next steps" in this project board.

[jtigger]

Done.

[kytrinyx]

Done as in can close, @jtigger ?

[jtigger]

No. I think I put that "done" on the wrong issue.

There are still a bunch of chunks to be pulled from the larger outline underneath the Q&A "guide."

Good time, though, to check in. Are we still happy with this direction?

[kytrinyx]

Good time, though, to check in. Are we still happy with this direction?

I think so!

[kytrinyx]

We now have the docs repository, along with a fantastic "finding your way / getting started contributing" guide from @jtigger http://github.com/exercism/docs