It is clear that most Clojure documentation (books, tutorials, blog posts) address Java or other language developers. I am at chapter three of the "Clojure Programming" book and so far I have seen many snippets of Ruby and Python code. That's not necessarily wrong but obviously the book assumes you are a Java, Ruby or Python developer. AFAIK, all Clojure books do. There is no lack of documentation addressed to experienced developers. But there is indeed a lack of documentation that addresses people who are just starting programming? This is because, I suppose, many in the community probably believe that Clojure is not suitable as a first programming language. This has been discussed on the list before and some in the community believe it is and some don't. I, for one, believe that a new developer or a computer science student should be able to go a long way learning Clojure and write applications with Clojure alone without any mention of interop until the very end. Such a book would be useful to anyone whether he is familiar with another programming language or not.
However, I think it is more of an advocacy problem that appears as a documentation one. It is as if the community is advocating Clojure only to existing developers. But Clojure is a hard sell to existing developers especially Java developers. It is better to advocate Clojure to new generations of developers, computer science students and professors and even power computer users (like Excel programmers!). These are not served as much with books and tutorials while existing developers are served very well. Why is Clojure hard to sell to Java developers? When Clojurians write about Java it is as if there is a love-hate relationship to Java and they have a conflicting message. First we tell them how bad Java (or their language is): "It is fine to hate Java and love the JVM"; Java is mutable and uncontrolled mutability is bad; it is imperative; Java's time model is broken and so on. But then after stating all the bad things about Java, we tell these enterprise guys who have invested a lot in Java: "wait, you can write Java in Clojure better than in Java". "You can still use all the (mutable, imperative) Java you have written over the years in Clojure." But I doubt that enterprise people and developers would do so for many reasons: a) All those concrete things around you look like objects that has properties and actions: this keyboard I am using; that car in the street, that toaster. It is very easy to sell OOP when you explain it starting with the concrete going to the abstract to a new developer and it sounds very natural. Most early examples in OOP books (about cars, people and things) sound immediately natural and practical. It doesn't matter that this model or analogy breaks very soon; the developer will have already been sold on the idea. That's what most existing developers are used to. In contrast, it is hard to "think" functionally about practical matters and most early examples in functional language books are about numbers and mathematics that are not "practical" to a new developer. b) Similarly, the imperative style of programming feels more natural as well to a junior developer and very similar to how "we do things in life". Algorithms, to them, are just recipes of steps; not mapping, filtering and reducing data structures which sounds "mathematical" (the horror). Just reference that library; do this, that, then a loop over a collection there and you're done and can go home and sleep all night. Functional programming, on the other hand, is high on the abstraction level from the very beginning; but the average developer doesn't care about high levels of abstraction. At every corner, a newcomer has to change the way he thinks to grok Clojure. Everything is completely different; even adding two numbers (+ 1 2) looks weird to what people are used to. c) It is easier to get used to Java syntax and it reads easily from the beginning. It takes longer time, probably months, and perseverance to get used to reading Clojure code. Try to read aloud some Java code and some Clojure code; the later sounds like reading algebraic equations; the former reads like sentences (albeit missing prepositions, ands and buts..). You scroll pages skimming Java code but you need to ponder for sometime to understand a Clojure function or a macro. It is as if there a hill on the road to learning the two languages; the hill is at the very beginning on the road to Clojure and it is at the end for Java. Iff a newcomer perseveres he will climb the hill and eventually get used to reading Clojure code and will appreciate how pithy it is. He will be shocked when he realizes that all he needs one-page cheat-sheet (for the language and most of its functions) instead of a huge reference for his language syntax and APIs. But that was a very big IF. Clojure is completely different in style, syntax and way of "thinking" than all those languages. You can move relatively easily from one language to another than from one of those languages to Clojure. I sound like I like Java more than Clojure :) but I am not. This, honestly, is how I imagine a Java developer would think trying to learn Clojure. Java feels more natural, easier to read and you don't have to think very abstractly right from the beginning. But those are for the people who look for "the easy". What I am trying to say is that even though it is easy to work with Java from Clojure, it is not reason enough for them to change. Most people don't like change and those who do, prefer to change to something that mixes between their world and a new world. Some functional stuff introduced in Java; LINQ in C# or another language that brings both worlds together. They do not like to leap to a completely different world. Advocating Clojure to computer science students (the future generation of developers) and professors has much better chances of success than to most experienced developers. Clojure would be very good for teaching computer science concepts. Instructors can use it to teach functional programming, probably logic programming and they can use Java in the same IDE to teach OOP concepts. When they graduate, these students will have learned computer science concepts in a language that they can actually use to write programs that targets widely popular platforms (JVM, CLR, JS,..) instead of languages the few use in the market no matter how suitable it is for teaching CS concepts. Unfortunately, the SICP-in-clojure book was a good step to provide documentation to these people but it was not finished. Generally speaking, the Clojure documentation doesn't serve these very well or address them. None of the Clojure books is written for them. They will need more books or papers about algorithms, data structures and more writings about the internals of Clojure data structures. The good thing is, from the blogs I read, I find that many in the Clojure community would love to write specifically to this audience about computer science topics using Clojure. Probably Clojure itself needs some work to advocate it to this group but I think that it will be possible in the next version of Clojure or the one after that. In addition to what has been suggested above like consolidating websites, I can think of few things that would help newcomers: - A "Clojure Tutorial" which I imagine would be very similar to the Java Tutorial but replaces all mentions of Java with Clojure and all Java code with Clojure code. This is the litmus test for Clojure as a first language. Again, that might not be possible right now, but going through the Java tutorial and writing the code in Clojure should point to what wrappers need to be written and possibly included in the core or the standard libraries. I haven't tried it but I think it is possible because there are already lots of Clojure wrappers for Java libraries as well as pure Clojure libraries. Few days ago, someone in the community ported two or three libraries to ClojureCLR. To his own surprise, it took him more time to post about his effort than port the libraries. This indicates that Clojure doesn't need too much added to the core to do a lot without a need for interoparting with Java. - This Clojure Tutorial can include screenshots from the Clojure-IDE (and VS + vsClojure for another tutorial ClojureCLR Tutorial). - This Clojure-IDE is actually Eclipse for Clojure (which integrates Clojure, Counterclockwise and lein libraries - not as external tools) and available as a single download. An update site for an eclipse plugin would be provided as well for other developers but not as the primary download. This is the only IDE that needs to be mentioned on the Getting Started page. - To make it easier for newcomer to climb the early hill, the best way to present clojure code is to show not only the end functions but the thought process that went into writing them. Something like this gist (git://gist.github.com/1684980.git) and literate programming for the more advanced code like those from Nurallah Nakkaya. I really hope that the developers in the community start saving the REPL logs and posting them as gists or in pastebins in addition to hosting the finished code. These has more teaching value with less effort than screencasts. They would be more helpful to understand how the code was written and help newcomers learn to "think functionally". -- You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to [email protected] Note that posts from new members are moderated - please be patient with your first post. To unsubscribe from this group, send email to [email protected] For more options, visit this group at http://groups.google.com/group/clojure?hl=en
