Stu- > (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.
That's +4 on this one by my tally, I'll pull the private vars. > (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. This is something I'd like to discuss in-depth on the new google group (http://groups.google.com/group/clojuredocsorg). It is something that I'd really like to see, but I haven't worked through the implementation details in my head (multiple versions stored per var vs. diffs stored, UI around this, etc). > (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. My first thought was to add some copy somewhere stating something to the effect of "By adding content to this site you are allowing said content to be licensed under the EPL." My second thought was that I'm not a lawyer :). Jokes aside, I agree that this is an important matter, and while the exact mechanism to accomplish this is unclear to me, the direct effect is not: I'd like users to be able to freely add to, copy, and modify any user generated content to facilitate learning the Clojure language and its libraries. > (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. If I had to map this out right now I'd say the order of operations within the scope of this point would be (c), then (a), then (b), and all after locking down the provenance issue you outlined above. I believe Justin also had concerns around this issue, and I think the short answer is that the amount of pain is going to be inversely proportional to time, but I'm committed to taking whatever measures are necessary to ensure that the hard work that went into adding content to the site would not be lost. I'll start a thread over at the clojuredocs.org group to discuss this. > 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. Sounds good, fix is up on the site. > 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. I think a mix of community and 'admin / editor' influence would be great here. Initially I'd like to provide an RSS feed for additions / changes to examples and comments. It's difficult to guess down the line because of the nature of the other issues that are up in the air right now, but I think we'll figure something out. Thanks again for the feedback. I think you've framed some important discussions about clojuredocs.org, and community documentation in general. -Zack On Jul 10, 8:06 am, Stuart Halloway <stuart.hallo...@gmail.com> wrote: > 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, andhttp://clojuredocs.orglooks 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 withhttp://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-pathto > >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
