Here are some thoughts about versioning and examples that were driving my github-wiki idea:
- Incompatibilities between Clojure versions are getting fewer and smaller. - This suggests that jumping from 1.4 to 1.6 will probably be a lot smaller than a jump from 1.2 to 1.3. - This implies that keeping multiple versions of the docs is not as relevant of a priority as it was during the 1.3 era. - It's probably sufficient to just have the "added in 1.x" line for each function, but keep its doc-string up-to-date with the latest Clojure version. - Plus, scattering examples between doc pages for different versions of Clojure will make it more difficult to find examples for functions that haven't changed between versions, since you'd have to search multiple pages unnecessarily. On Wed, Sep 11, 2013 at 7:51 AM, Alex Miller <a...@puredanger.com> wrote: > Hey all, > > Lee Hinman (dakrone) is the current primary maintainer. There was a good > discussion about clojuredocs last year at the conj unsessions and I think > the primary driving note that came out of that was that it would be useful > to have the concept of version in the database (that is, examples are tied > to versions). That was going to drive some changes in the data model. > > I talked to him recently about the state of clojuredocs. I know he's been > pretty busy lately with a new job. I believe he thinks the service API and > doc extractor are in pretty good shape. The major areas that need work are > figuring out how to store the data in a database (I think he's just indexing > right now with Elasticsearch) and actually creating the front end > (preferably in Clojure of course) that used the existing API. If it was > desirable to use Datomic, I suspect we could probably work that out. :) > > If someone was interested in working on these areas, help would be greatly > appreciated! This is an awesome opportunity to work on a greenfield Clojure > web app that would be used by the community. It would be helpful if we had > one or more point people who had the time and enough experience to organize > and lead such an effort. I'm sure Lee would be amenable to that based on our > conversation. > > Alex > > > On Wednesday, September 11, 2013 3:42:40 AM UTC-5, xavriley wrote: >> >> I've just picked up on this thread but I've spent quite a bit of time >> barking up this tree. >> >> There are three repos that power the old version of the site >> >> https://github.com/zk/clojuredocs - the Rails 2 frontend >> https://github.com/zk/clojuredocs-analyzer - the clojure analyzer that >> extracts data from Clojure Core and other projects >> https://github.com/zk/cd-wsapi - the API that handles CLI integration >> >> I've got a pull request sitting there for the analyzer which makes it work >> with Clojure 1.5.1 >> >> https://github.com/zk/clojuredocs-analyzer/pulls >> >> But I've not had any response from the maintainers yet. I've tried >> catching them on IRC but I haven't heard anything since I submitted the PR. >> >> I could just host a fork of Clojuredocs myself with 1.5.1 but I think >> that's the wrong way to do this. I have had some success in forking the >> project for Overtone documentation and Core.logic docs which you can see >> here: >> >> http://overtone-docs.herokuapp.com/ >> http://corelogicdocs.herokuapp.com/ >> >> So it's entirely possible to work with what's there. I'll try getting in >> touch with dakrone to see if we can make this update happen. >> >> >> >> On Wednesday, September 11, 2013 8:57:21 AM UTC+1, Colin Fleming wrote: >>> >>> Something that I've always wondered - why is ClojureDocs not updated? >>> I've never tried to contribute to it - is it particularly difficult? Is it >>> impossible for users to add support for new Clojure versions? If so, who >>> runs it? Could it be turned over to the community? >>> >>> >>> On 11 September 2013 17:55, Steven Degutis <sbde...@gmail.com> wrote: >>>> >>>> All very good points. >>>> >>>> One of my assumptions was that people don't use wikis simply because >>>> it's Yet Another Account to sign up for, so this being hosted on >>>> github would be a much lower barrier-to-entry for contributing >>>> examples. But I'm not sure that's a valid assumption for anyone >>>> besides just me. >>>> >>>> And I wasn't suggesting that the structure be edited. I was imagining >>>> an unwritten rule where only examples would be edited/added, and the >>>> rest of the structure of each page remain the same. That would make >>>> parsing the wiki partially manageable. But I'm not sure how realistic >>>> that is in practice. >>>> >>>> Thanks for your feedback. >>>> >>>> -Steven >>>> >>>> On Wed, Sep 11, 2013 at 12:39 AM, John Gabriele <jmg...@gmail.com> >>>> wrote: >>>> > On Sunday, September 8, 2013 4:07:33 AM UTC-4, Steven Degutis wrote: >>>> >> >>>> >> >>>> >> https://github.com/sdegutis/clojuredocs/wiki >>>> >> >>>> >> {snip} >>>> >> >>>> >> Thoughts? >>>> >> >>>> > Hi Steven, >>>> > >>>> > This is a nice piece of work. Thank you. >>>> > >>>> > Some thoughts: >>>> > >>>> > * Wikis are difficult to keep nice. And, seemingly contradictory to >>>> > that, >>>> > it's difficult to find contributors. >>>> > >>>> > * There is already a Clojure wiki, >>>> > <http://en.wikibooks.org/wiki/Clojure_Programming>, but it does not >>>> > see many >>>> > updates. >>>> > >>>> > * I really like clojuredocs.org's clean (and enforced) separation of >>>> > examples, see-also, and comments. >>>> > >>>> > * Although github's wiki feature is handy, for a pure wiki there are >>>> > better solutions, IMO (for example, my favorite is >>>> > [gitit](http://www.gitit.net/)). >>>> > >>>> > * I think some of the work necessary to replace/rewrite >>>> > clojuredocs.org >>>> > has already been done by dakrone. Dunno the status of it though. >>>> > >>>> > * I think it's worthwhile to pull docstrings directly from Clojure >>>> > itself. >>>> > Fixing docstring typos in a wiki is nice, but I'd rather see fixed the >>>> > actual source docstrings themselves... >>>> > >>>> > -- John >>>> > >>>> > -- >>>> > -- >>>> > You received this message because you are subscribed to the Google >>>> > Groups "Clojure" group. >>>> > To post to this group, send email to clo...@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+u...@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 unsubscribe from this group and stop receiving emails from it, send >>>> > an >>>> > email to clojure+u...@googlegroups.com. >>>> > For more options, visit https://groups.google.com/groups/opt_out. >>>> >>>> -- >>>> -- >>>> You received this message because you are subscribed to the Google >>>> Groups "Clojure" group. >>>> To post to this group, send email to clo...@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+u...@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 unsubscribe from this group and stop receiving emails from it, send >>>> an email to clojure+u...@googlegroups.com. >>>> For more options, visit https://groups.google.com/groups/opt_out. >>> >>> > -- > -- > 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 unsubscribe from this group and stop receiving emails from it, send an > email to clojure+unsubscr...@googlegroups.com. > For more options, visit https://groups.google.com/groups/opt_out. -- -- 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 unsubscribe from this group and stop receiving emails from it, send an email to clojure+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/groups/opt_out.
