February 12, 2017

[Exercism: Behind the Scenes] Explaining stuff is hard

Back when I started this project, the documentation went something like this:

- Clone the repo
- Make your change
- Submit a PR

There's a lot missing from that.

After a while, people would report that it was hard to get things running locally, so we ended up with a massive wall of text in the format:

- type this
- change directory
- run this command
- check that
- do this other thing

... on and on and on.

What we didn't have until now is the thing that would let someone who has a cursory knowledge of Exercism figure out where to begin.

The start of contributing to Exercism isn't about cloning a repository, it's about finding the right repository to contribute to. And that, in turn, isn't just about going to the Exercism profile page on GitHub and looking at the repositories. That doesn't provide a good mental model of what you're looking for and how things fit together.

So I've made an attempt at documenting Exercism—the open source project. I'm not trying to explain how you would use Exercism to learn a new programming language, or why you might do that. I'm trying to give you a way to start considering the project if you think you might want to contribute to it.

Exercism—as an open source project—has two distinct parts.
 
  1. The Product
  2. The Curriculum
Most open source projects are code that people incorporate into their own projects. They're tools and components used to build software: libraries and frameworks, packages and infrastructure.
 
Exercism is unusual in the open source landscape. Exercism isn't a component or infrastructure. Exercism is an experience targeted at the end-user.
 
If you want to follow along on the high-level goings-on on the Exercism project, watch the discussions repository, and keep an eye on this newsletter.

The Product
 
The product consists of a website and a command-line client (CLI).
 
We are currently investing our efforts in design research and product design.
 
While we welcome fixes and improvements to the existing site, we are taking a step back from it and doing design research from scratch. You can read more about this in the article The Delightful Design of Exercism.
The website lives in the exercism/exercism.io GitHub repository, whereas the CLI is in exercism/cli.

The Curriculum
 
The curriculum is much more like a traditional open source project than the product is. It consists of many small, well-defined components, and it is a lot easier to contribute to.
 
The goal of the curriculum is to create many small, trivial exercises. These provide lots of achievable challenges, giving people many small wins.
 
There is a common pool of exercises and the exercises are implemented in many different programming languages.
 
We have a library, Trackler, that provides a unified interface to the entire curriculum.

The Common Pool

An exercise is a description of a problem to solve. This description is not specific to any particular programming language or library or tool.

An example is:
Determine whether or not a word is an isogram.
You could do this on the back of a napkin, or on a whiteboard, or by writing code.

There are many ways to contribute to the common pool:
 
  • fix typos
  • improve exercise descriptions
  • document edge cases
  • discuss philosophical questions
  • make up more exercises
  • define canonical data-sets to make it easier to implement the exercise
The common pool is maintained in the exercism/x-common repository.

The Language Tracks
 
A programming language that implements exercises from the common pool is called a language track.
A language-specific implementation of an exercise consists of a collection of automated tests, that define the requirements of the solution.
 
A good test suite will not mandate a particular approach, but will allow people to try many different approaches, and solve the exercise in many different ways.
 
There are many ways to contribute to a language track, described in the document Getting Involved in a Language Track.
 
You can navigate to the repository for any language track on Exercism via the trackler library. This list includes both active and upcoming tracks, as well as tracks that have been requested where no work has yet been done.
 

I've put this content into a pull request (https://github.com/exercism/exercism.io/pull/3377). If you have thoughts or suggestions or feedback, I'd appreciate it if you would help review the PR.