A very even-handed, honest and accurate evaluation of Clojure, at least from my somewhat limited perspective. I've written a couple of small/trivial programs in Clojure and read a couple of the books ("Joy of" and "Practical"), so I'm far from an expert.
I will say that the online documentation IS atrocious and basically impenetrable, and usable code samples are quite difficult to come by. That being said, it's a very young language, with a very active, helpful and -- dare I say -- friendly IRC channel. (And by the way, a couple of top-notch eval bots)
The documentation piece is easily overcome by spending $20 on an ebook. Joy of Clj and Practical Clj are both very readable & accessible. The code samples are clear and concise, and the explanatory prose is excellent.
IDE support... well, I use emacs. It's widely recommended people use emacs for Clojure simply because it is so well integrated with it. REPL and line evaluation are fantastic in emacs. People who don't like/want emacs tend to use vim's Clojure mode, at least according to IRC.
I will say that the main pain point I had in getting started with Clojure was building the environment. The "best practices" for a Clojure environment has shifted wildly, as far as I can tell, over the past few years, so most/many of the blog posts that describe how to get it set up are wrong, or very dated and unsupported by current software (e.g. Leiningen).
All in all if you are interested in learning Clojure, you are doing yourself an enormous disservice by not joining #clojure and asking your questions there.
Your comments about the build system do bring up a good point. Perhaps leiningen or cake should be adopted as a default build tool and integrated into the main code base and website.
I admit that the complaints about the lack of examples in the documentation does confuse me a bit. The documentation sites for C and C++ don't seem to include examples either. For me, tutorials and books were always the go to places for examples. I will agree whole heartedly that some of the 3rd party libraries like ring/compojure need some serious documentation improvement, in particular since the architecture of these libraries is fairly complicated.
Could someone link examples of good documentation they like from other languages to help clarify?
C and C++? Dude, there's a whole generation of programmers -- paid, successful, professional, prolific programmers -- who have never even looked at C or C++. Or, if they did, it was for a couple of classes and haven't touched it since.
Making C/C++ documentation the standard for documentation is like making a Chevy Nova the standard for features in modern automobiles.
About the IDE: I've tried using Emacs, and I've actually managed to do it for a good while, but when I finally discovered Eclipse's Clojure plugin, it was as if big chunks of iron were removed from my hands. Emacs is simply not for everybody. Eclipse's Counterclockwise (the Clojure plugin) may not be as rich in features, but it's easy as pie to install and start using.
thanks. which of those books goes furthest? (i imagine i can work out the basic stuff, so it seems best to choose whichever includes the most obscure/advanced features - and i'd like to save time by reading just one...).
i do use emacs for text editing, so i'll try it for clojure (i should say that there was only one wrinkle in getting the environment working in intellij - that was adding clojure.jar to the classpath, which it told me to do in an error popup, so it wasn't hard at all).