Very cool. Let me start by saying thanks to everyone who has been involved in the various threads on improving documentation, especially those who, like Zack, have taken substantial action.
Here are a bunch of ideas, in no particular order: (1) Ease of contribution is huge, and http://clojuredocs.org looks good on this front. Stick to it. (2) +1 on hiding private APIs. We use private APIs carefully and deliberately in Clojure, and I would hate to facilitate people writing code that will break later. (3) +1 on making it very easy to see which version of an API you are looking at. This should be both at the top level (some way to say "show me 1.1") and on a per-var basis, reading the :added metadata. (4) Provenance matters. Clojure itself is very careful to have people sign a CA before contributing code. The bar may be somewhat different for a documentation site, but it still needs to be carefully considered. (5) Continuity matters. We have already had some pain with useful resources popping up on the web and then having the maintainer go AWOL with no succession plan. There are several steps any documentation site should take to address this: (a) open sourcing everything (b) including multiple committers and admins on the site itself and (c) providing an easy API to suck the data out. (6) Because docstrings are designed for consumption at a REPL, they may in some cases presume a fixed font. Worth considering for display on the site. (7) Quality matters. There are multiple possible ways to make sure that the cream rises: letting people up and downvote, making it easy for "editors" to track new submissions, etc. Thanks again! Stu > Hi All, > > I'll try to keep this short. > > I've gotten a lot out of Clojure: I can honestly say that learning > this language, and being part of this community has made me a better, > happier developer, and I wanted to give something back. > > One of the pain points that I encountered when learning the language > was a lack of examples specific to the individual functions I was > trying to wrap my head around at any given time. So I took a whack at > the problem, and came up with http://clojuredocs.org. It's a site > that (I'm hoping) will fill this need by providing a centralized > examples database, along with solid search capabilities across both > core and third party libraries (core being the focus). > > Implementation: > ClojureDocs.org is a rails site backed by MySQL, along with some > clojure code to pull the namespaces / metadata / source and dump them > into the database. > > Highlights: > 1. Documentation and source for Clojure core, contrib, and a few third > party libraries (random selection out of what I'm personally familiar > with, and whatever was on the github trends page that day). > > 2. Search for a var across the whole ecosystem or in a specific > library. > > 3. Per var wiki-style examples section. > > 4. Per var comments section. > > 5. Per var vars-in-this-var and this-var-used-in section (my personal > favorite). Looking for a real-world example of a specific function? > This is for you. For example, http://clojuredocs.org/v/1978, just > below the source section. > > > Lowlights: > 1. Ugly URLs! There's a problem in the way that URLs with encoded > question marks are being handled, so I had to move from > http://clojuredocs.org/clj-ssh/clj-ssh.core/file-path to > http://clojuredocs.org/v/1484. I've got an email out to the Phusion > Passenger mailing list (http://groups.google.com/group/phusion- > passenger/browse_thread/thread/ed2eadfdac5c166f) but if you've got any > experience in this area drop me a line. > > 2. Strange var names (http://clojuredocs.org/v/781). Probably a bug > in the import process. > > 3. General rough-around-the-edges-ness. > > > I'm treating this as an alpha, and I'd really like feedback as to: > a. How useful this would be to the community. > b. Specific likes / dislikes about this alpha release. > c. Feature requests. > > I've set up a feedback mechanism directly through the site (User > Voice), which allows voting on specific posts. I'm also considering > setting up a google group for general discussion. Feel free to > contact me directly through email. > > Questions / thoughts? > > -Zack > > -- > 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 -- 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
