UVTC's Blog

2012-10-09

Wow, it’s been a pretty busy couple of weeks in the world of Clojure documentation.

A number of recent threads came up on the ML about the state of Clojure documentation, so I thought I’d finally write a Clojure tutorial, and maybe also see what other docs other folks might write to go along with it. I imagined a sort of organic “sundry bunch of docs” type of project: less formality than “official” documentation, but more boundaries than a wiki (i.e., “don’t go editing other people’s docs with wild abandon”). Along with the tutorial/introduction, I also wrote up a tut/getting-started guide, a community.md doc, and a cookbook article, and put them all up on github. Everything was being rendered in lovely html using Pandoc. I wrote a little tool for running Pandoc on all the docs and creating a table of contents: rippledoc.

A number of others seemed interested in this sort of a project, and we began discussing it on #clojuredocs (edit: now #clojure-doc). A name was chosen: “CDS”. Not my first (or second, or third ☺) choice, but hey, community projects require compromise, and anyway, it began to be regarded as something that would eventually be hosted at a future docs.clojure.org (and the logic went that it therefore wouldn’t really need an interesting name anyway).

I created an organization for the cds project and announced it.

Some folks wanted to convert it over to render html using the same doc tools as clojurewerkz.org (that is, using jekyll). Personally, I preferred the more plain output using my little rippledoc tool, but others preferred the clojurewerkz style and the conversion was done. Michael K even got a domain where the output could be made available: http://clojure-doc.org/.

The announcement of the new reworked CDS site went up.

Some of my original ideas for the project have been abandoned. For example, adding new docs must now be discussed and agreed upon beforehand. And editing other people’s docs for style is now considered ok in order to eliminate duplication and keep things looking like official technical documentation. Perhaps this is what’s needed if the docs are to become the official Clojure docs.

I think it’s great that the Clojure community has now got a centralized docs project where it’s relatively easy to contribute, and I look forward to seeing CDS continue growing.