As the author of the book, you can bet I have an opinion on the quality of the docs. :-)
(1) I think the documentation for Clojure (website, Mark Volkmann's long article [1], blog posts, the book [2]) is *insanely* good, given how young the language is. But... (2) If you are coming from a mainstream business software environment, there are a ton of new ideas in Clojure. There's more to learn, so of course it is going be harder, and take longer. You won't get there just by reading one book, even if you work through all the code examples. I *love* that Rich's recommended reading list [3] has not 2, or 4, but 36 books!! Clojure stands in opposition to the "in 21 days for dummies" [4] school of thought. (3) Scala's just as hard to learn, because it too is full of ideas that are new to many developers. I would love to see the 36-book list for learning Scala, and I bet there would be significant overlap. (4) I think the Clojure docstrings are ok, but could be improved by usage examples. Rich, are you interested in patches that simply add examples to docstrings? In short: if you are the median developer, both Clojure and Scala are huge improvements over the language you are using right now. But you won't be effective in either one of them tomorrow: the learning curve is not 1, but 5-10 books. So let's raise the bar. In the world I want to live in, programmers above the novice level would understand the ideas in both Clojure and Scala. Learn both. :-) Cheers, Stu [1] http://java.ociweb.com/mark/clojure/article.html [2] http://www.pragprog.com/titles/shcloj/programming-clojure [3] http://tinyurl.com/clojure-bookshelf [4] http://norvig.com/21-days.html > > I think there are a lot of people who need to choose between Clojure > and Scala to study as a "new" language. I must say that both are bad: > * Clojure doc is hard to understand. > * Scala grammar is complicated. > > I prefer Clojure. I think Clojure feature at this time is OK, thus the > decisive point to draw people to Clojure is doc. I wonder if the doc > at this time is obvious for LISP people, but comming from C/C++, Java, > Ruby, and Erlang (Erlang doc is bad, but it is paradise compared to > that of Clojure :D) and even after reading the Clojure book, I must > say that I can't understand 99% of the doc of both clojure and > clojure- > contrib. > > For example, what does the following mean? > ------------------------- > (-> x form) > (-> x form & more) > Macro > Threads the expr through the forms. Inserts x as the second item in > the first form, making a list of it if it is not a list already. If > there are more forms, inserts the first form as the second item in > second form, etc. > ------------------------- > > My wish: There are easy-to-understand examples in API doc. > > Rails is easy to use largely because there are examples in doc of > every API function. > > > On Aug 26, 12:37 pm, Alan Busby <thebu...@gmail.com> wrote: >> On Wed, Aug 26, 2009 at 5:43 AM, npowell <nathan.pow...@gmail.com> >> wrote: >> >>> I mean, I didn't think the article was terribly in depth, but a >>> real, >>> evenhanded comparison would be enlightening. >> >> Reducing it further, I'd be interested just to hear more about the >> contrast >> of static typing versus macros. Which is more beneficial for >> different >> situations and why? > > --~--~---------~--~----~------------~-------~--~----~ 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 -~----------~----~----~----~------~----~------~--~---
