There was an interesting conversation today on #clojure about various aspects of Clojure documentation. This is not a new topic I thought I’d goose it a little more publicly.
There are docs in several places (this is incomplete, but most easily found):
- clojure.org – “official”, first-stop, very small editor set
- dev.clojure Confluence – wiki, editable by many but less formal. Important parts include the Getting Started pages in particular.
- Clojure Docs – a place to stash per-function examples in core and libraries
- Learn-Clojure – a gathering of “learning” resources
At last year’s conj, I was inspired to improve http://clojure.org and talked Stu into letting me make some changes
Eventually, my free time ran out and I declared doc change bankruptcy and just put my todo list on the dev site. In general these changes were ideas and I didn’t feel comfortable to make them without /core approval. Subsequently, Rich, Stu made some changes and a few other people stepped for things like updating the cheat sheet and making it a bit more maintainable.
If you come out of the conj inspired to do some doc work to improve your world, here are some suggestions:
- When you have trouble using a function and you finally figure it out, add an example to ClojureDocs. It’s easy and it helps the next guy.
- Pick up one of the items on the .org TODO list (or add your own pointy edge). Write some replacement text or set of edits. File a jira with your change so /core can review. I’m happy to offer to do the replacement work once it’s been blessed or one of the other site editors can do it.
- Offer to help with http://learn-clojure.com – Kyle Cordes created the site and has plans to improve it but he is open to help.
- Update the pages on the dev wiki, especially the Getting Started pages.