March 19, 2017

[Exercism - Behind the Scenes] Documenting the non-obvious is non-obvious

I'm just going to put this right here: writing documentation is hard.

I've complained written about it before. I've complained said that I don't quite understand why people suggest that writing documentation is a great way to start making contributions to an open source project, because documentation is about synthesizing a whole lot of detail and understanding so that those who are unfamiliar with the project can become familiar with the project. How is someone who is unfamiliar with the project going to do that?

I mean, sure—when following the setup instructions you will certainly catch typos and find sentences that can be rewritten for clarity, and discover that an explanation is outdated or missing.

But technical writing? Not easy.

Last week Ian Whitney noted that there was quite a bit of duplication between documentation in different Exercism repositories and suggested that we put all the documentation in one place.

As a result, we now have an exercism/docs repository, which is pinned on the Exercism organization page, and has a tracking issue where we're coordinating the work to organize, move, and deduplicate the documentation.

While writing documentation from scratch can be nearly impossible without being familiar with the project, helping organize and move documentation is one of those things that is quite doable for newer contributors.

To follow along or help out, check out the tracking issue here: https://github.com/exercism/docs/issues/2