I'm very excited to see how quickly the Clojure community is taking up the charge of improving the documentation!
Within a few *days* of my "Clojure n00b problem" post, several solutions have emerged to take up the cause of providing proper documentation and examples for Clojure's API, and third-party APIs as well. I don't know whether that post had anything to do with it, and frankly it doesn't matter. The projects that have emerged are: http://clojure-examples.appspot.com/ http://www.clojuredocs.org/ Further, I noticed several other reactions in this group of people stating they were planning on doing the same thing. You can add me to that list. :-p I'm worried, however, about the problem of fragmentation. This is a very serious problem that affects many projects, companies, etc. Providing good documentation and examples for Clojure's APIs, as well as third-party libraries, is *not* an easy task, and I doubt very much that a good result will emerge in the existence of a fragmented playing field. It would be a wish come true for me if Clojure's documentation were as good as PHP's or newLISP's. The only way that's going to happen is if efforts are not fragmented. Notice that both of those examples are examples of non-fragmented, focused community efforts. Clojure currently has at *least* 3 locations for API/examples. The two efforts above, and the existing Clojure.org/api. I have a feeling that more are on the way. I'd like to propose that we address this problem immediately, before it gets worse. We need to have one, single, awesome goto location for examples and documentation. Without that Clojure's documentation will remain third-rate. I think such a website must include, at the very minimum: 1) A way for anyone to easily add and edit examples and documentation. 2) For functions to be grouped by task/category 3) API access to the documentation and examples via JSON, so that IDEs can hook into it and provide documentation inline while you're editing. 4) Simple and easy methods for third-party developers to add their project(s) to the site. 5) Site-wide search on function/namespace names, documentation, and examples. And this is the "it would be nice" list, (again, all my opinion, of course): 1) Comments by users. 2) For the comments to be parsesable in markdown/textile so that commenters can post syntax-highlighted code. 3) Community voting and replying on individual comments ala HackerNews. 4) Live-updating searching in a frame/div in a section on the left to filter for functions/namespaces. 5) For the site to be powered by Clojure. Call me old-fashioned, but I think it should be. :-p 6) A better clojure-doc to integrate developers with the site. It would be great if developers could provide the initial documentation to such a site by running a tool like javadoc on their code. With regards to the minimum, #2 (task/category), is one of the most important (IMO). Have a look at how newLISP does this: http://www.newlisp.org/downloads/manual_frame.html The left-navigation bar makes it incredibly easy to find what you're looking for. PHP does something similar. I wouldn't consider a documentation site "good" without it. The practice of listing namespaces and then the functions within them in alphabetical order on one massive page isn't helpful. It's not helpful for learning an API, and it's not helpful for quick-reference. ============================ Possible solutions to fragmentation ============================ As I mentioned, I was (and still am) planning on addressing this issue if it's not solved well by another effort. But I don't want to add to the fragmentation either. Shortly after posting "Clojure n00b problems", I registered clojuredoc.org for that purpose. I'm now not so sure what to do with it, but I have some ideas. I have two proposals: Proposal #1: Combine clojure-examples & clojuredocs.org -------------------------------------------------------------------------- clojure-examples is already on Github. This is good, it means anyone can contribute and improve the site. It's also powered by Clojure. I think it'd be great if the two efforts combined forces and combined their documentation/comments/examples. I'd be happy to hand over clojuredoc.org to such an effort. Proposal #2: Central database of documentation and examples --------------------------------------------------------------------------------- If for some reason you don't want to combine efforts on the front-end of the site, clojuredoc.org could server simply as a backend for holding all the data. This way clojure-examples and clojuredocs.org (and IDEs) could pull & push examples/comments/documentation from a central location. This way, when someone submits examples on one site, they're available for all sites to use, and thus effort is not fragmented. Comments/Feedback welcome (especially Zachary Kim and Justin Kramer, and anyone else who is working or is interested in working on these frontends/backends). Cheers, - Greg -- You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@googlegroups.com Note that posts from new members are moderated - please be patient with your first post. To unsubscribe from this group, send email to clojure+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/clojure?hl=en
