Because of an moderation problem with my email (https://groups.google.com/group/clojure/browse_frm/thread/90c0a82153e08c9c) this thread is a bit outdated already.
Perhaps it should be merged with the ClojureDocs.org thread now, as Tim and Justin apparently already seem to agree on collaboration (which is great!). - Greg On Jul 9, 2010, at 12:33 PM, Greg wrote: > 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 -- 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
