This is a project proposal for Google's Season of Docs support.
Exercism is a not-for-profit organization that helps people develop and improve their programming skills through practice and mentoring. Our platform is made up of over 200 GitHub repositories covering nearly 70 programming languages. Everything is Open Source. Since launching in 2013 we have helped over 500,000 people become better programmers.
Good communication is at the heart of Exercism. The heart of our platform is mentoring, where strangers help each other understand and fill knowledge gaps, and where empathetic communication is essential. The product is built by volunteers — so creating a fun, exciting and enticing place to build together is a key part of our mission.
One of our challenges is that Exercism is a large project, which can make knowing where to start intimidating and overwhelming. Ensuring that contributors have a frictionless contribution experience, are able to find and adhere to our guidance, and (most importantly) feel like they can communicate clearly in the "Exercism way" with our other contributors, is vital.
As we have developed tighter quality-control and implemented firmer standards across different parts of the project, there is more that new contributors have to understand to get started, which has increased the barrier to contribute. We need to ensure that new contributors can find both clear introductory paths and comprehensive supporting details when needed. Good documentation is absolutely critical to ensuring that new contributors can find pathways to get started, and not get blocked or feel frustration while trying to help. We believe it is a crucial part of enabling Exercism to reach its potential.
New contributors not only help Exercism grow, they provide important improvements in the experience for hundreds of thousands of new students who use our platform each year.
As part of the approaching launch of our new version of the site launch, we have developed a whole "docs" mini-site. You can preview the WIP version here: https://exercism.lol/docs
The project has the following goals:
- Work with Exercism's team to understand the gaps in our existing documentation
- Design a structure incorporating our existing and newly conceived docs
- Flesh out that structure with stubs for new docs, and crowd-source feedback on the best information to go into docs.
- Create missing documentation and reorganize existing docs as required.
- Welcome and incorporate feedback from our team of maintainers, and the wider Exercism community.
- Help develop guidance to empower language tracks to create their own per-language documentation.
Work that is out-of-scope for this project:
- Working on natural-language translations
- Work on educational content for Exercism itself
- Work on individual language-track's docs (other than working on an exemplar language for point 6)
We would consider the project successful if, after the completion of the project:
- The community contributes further documentation improvements (taking pride in our docs). Currently this rarely happens outside of the senior team, so any contributions would be a marked improvement.
- The number of new contributors making meaningful changes to Exercism in the 6 months that follow publication increases by 100%. We define a meaningful change as where someone will have needed to utilize our docs to make the change.
- The number of PRs from existing contributors increases by 20% over the subsequent quarter.
| Item | Cost | Running Total | Notes/justifications |
|---|---|---|---|
| Technical writer to structure docs, create documentation, and create guidance for future contributors | $12,000 | $12,000 | |
| Supporting Volunteers to help provide guidance to the technical writer | $1,500 | $13,500 | 3 volunteer stipends x 500 each |
| TOTAL | $13,500 |
The right technical writer will be as focused on clear and empathetic communication as on technical correctness. It is critical that our docs are written in a friendly and welcoming tone, and that they feel exciting and warm. Making it clear to new (and existing) contributors that Exercism is a great place to spend your time is a critical component of our docs.
We have reasonable technical specifications for many parts of Exercism already, which have been developed by our maintainers team, and while help and advice on these is welcome, they are not the focus of this project.