The Clojure documentation project started off quite actively. With several new guides and a dozen of contributors, the resource is already quite useful to newcomers to the language. We believe this is directly related to our straightforward contribution process.
CDS Progress Report
A week ago we announced the new Clojure Documentation Site (a.k.a. CDS) effort. The level of activity in the first week exceeded our expectations and we thought it may be a good idea to publish periodic reports (every week or two) to give the Clojure community a better idea of what CDS shapes up to be and what it has to offer.
So lets start. This is a report for the week ending October 14th, 2012.
In a Gist
In the first week of CDS, we have added
- 2 new tutorials and 6 new and 2 expanded guides
- About 4,000 lines of changes in the content directory (does not include CSS or toolchain-related changes)
- 14 merged pull requests
- 13 contributors
- About 1,400 unique visitors
- About 6,000 page views with average visit duration of 2 minutes and 10 seconds
In addition, we have ironed out first issues in the contribution process and set up an IRC channel (
contributors coordinate their work.
- clojure.core Overview
- Interoperability with Java
- Polymorphism: Protocols and Multimethods
- Collections and Sequences
- Clojure Glossary
Thank You, Contributors
CDS would not be possible without the following people who make Clojure community a better place:
- Gareth Jones
- John Gabriele
- Claudio Perez Gamayo
- Phil Hagelberg
- Lee Hinman
- Michael Klishin
- Julson Lim
- Jake McCrary
- Max Penet
- Oleksandr Petrov
- Robert Randolph
You Can Help!
How It Works
We have a repository on GitHub that has Markdown files, toolchain setup instructions and several articles as well as stubs for several more articles. The stubs help contributors pick a topic to write about and not worry too much about article structure initially. Just pick something that you are very familiar with or interested in and write.
When you are done, submit a pull request on GitHub and someone from the existing contributors team will suggest improvements or merge your work. Pretty straightforward.
In order to make it easier for potential contributors to join the project, we will post a brief list of guides that do not require deep expertise and can benefit from contributions by complete beginners.
Tutorials that need work:
Guides that have structure and good chunk of the content in place but still have many holes you can help us plug:
If you want to start working on one of those articles or have existing content you’ve authored that can be ported, please let us know on the Clojure mailing list.
But It Takes Forever/I’m Not A Good Writer/[Insert Your Excuse Here]
If you need examples of what’s possible, here’s what 2 ClojureWerkz core team members could produce in about 6 months in their spare time:
- Monger documentation
- Neocons documentation
- Welle documentation
- Elastisch documentation
- Langohr documentation
- Quartzite documentation
Both ClojureWerkz core team members are not native English speakers. You certainly can contribute even if you allocate 30 minutes per week for it.
Other Ecosystem Documentation Improvements
CDS is about improving Clojure documentation all around the spectrum: from tutorials to language guides to documentation about important parts of the ecosystem. One of the fundamental building blocks of the Clojure ecosystem is Leiningen. There were two improvements to Leiningen documentation this week:
- The Leiningen tutorial got an update
- A new guide was added: Managing Polyglot (e.g. Clojure/Java) Projects with Leiningen 2
CDS is shaping up quite nicely. With over a dozen of contributors and 8 piece of content contributed the first week, the progress has exceeded our expectations. The Clojure community still has very long way to go with respect to documentation but this is encouraging.
And, you can help!
On behalf of the Clojure Documentation Team