News Feed Comments

You are here: Home / Clojure / Improving Clojure’s docs

Improving Clojure’s docs

2

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 <evil-laugh/>. In particular, all of the API references on the site pointed to the old richhickey github repo and I switched all of those over. There were a number of other small changes I made as I ran into them and saw other ideas. I asked in a few public forums for suggestions and started keeping a list.

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:

  1. 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.
  2. 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.
  3. 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.
  4. Update the pages on the dev wiki, especially the Getting Started pages.

Posted by on Thursday, November 10, 2011 at 2:10 pm 
Filed under Clojure · Tagged with

Comments

2 Responses to “Improving Clojure’s docs”
  1. Craig Tataryn says:
    November 16, 2011 at 5:11 pm

    It would be awesome if for every API entry, there was a link to a real example. So when I type (doc str) I get all the API info + a link to a real example showing its usage. If pictures speak a 1000 words, so to do examples.

  2. Bryan Deter says:
    December 11, 2011 at 1:49 am

    I was thinking about the examples from Craig’s comment, and decided to take a quick peek at the test code for the main Clojure project and saw some wonderful examples of actual usage. It’d be interesting to look for a way to pull in those as examples (maybe a source link from the API docs)