Gregg Williams <greg...@innerpaths.net> wrote: >Steve Yegge's main idea, that "Clojure needs to start saying yes," is >true on multiple levels.
It's also BS on multiple levels, which probably has more to do with Steve's reputation than anything else. But I want to address your focus: >I'd like to focus the community's attention >on a neglected area that I believe is extremely important to Clojure's >success. I'll do so by restating Steve's main idea in slightly >different words: >The Clojure community is, overall, newcomer-hostile. [...] >Let me give you some examples. > >EXAMPLE 1: clojure.org > >Clojure.org is probably many newcomers' first exposure to the >language. On the "Functional Programming" page, the second page with >actual code in it, the reader is introduced to the defn keyword as >follows: > >----- > defn is a macro that makes defining functions a little simpler. > Clojure supports arity overloading in a single function object, >self-reference, and variable-arity functions using &: > > (defn argcount > ([] 0) > ([x] 1) > ([x y] 2) > ([x y & more] (+ (argcount x y) (count more)))) > -> #'user/argcount > (argcount) > -> 0 > (argcount 1) > -> 1 > (argcount 1 2) > -> 2 > (argcount 1 2 3 4 5) > -> 5 >----- > >And that's all it says. And that's pretty much exactly what it should say. >Imagine being a newcomer to the language, probably someone who is >unfamiliar with any version of Lisp. Look at the terminology. What is >"arity overloading"? What is a "single function object"? What does >"self-reference" refer to? What does "using &" mean? And how does the >code sample work? If you've never seen Clojure code before, how could >you possibly expect this code snippet to make any sense, given this >*and nothing more* ? Go back and look at the clojure.org again. Does that look like an intro pages for a new programming language to you? It certainly doesn't to me - it looks like an abstract or forward for a reference manual for that language, what with a table of contents for such a reference manual along the left, and apparently no instructions whatsoever on how to actually get a copy of Clojure running somewhere. >Let's say the newcomer is lucky enough to get a REPL working. He >decides to use the built-in help system to find out more about defn: > >----- > user> (doc defn) > ------------------------- > clojure.core/defn > ([name doc-string? attr-map? [params*] body] [name doc-string? >attr-map? ([params*] body) + attr-map?]) > Macro > Same as (def name (fn [params* ] exprs*)) or (def > name (fn ([params* ] exprs*)+)) with any doc-string or attrs >added > to the var metadata > nil > user> >----- > >Now imagine you're the newcomer who's used to looking at Java code. Then you're looking at the wrong thing. You should be reading the (unfortunately non-existent as far as I know) intro to reading Clojures automatically generated function documentation. If the clojure community says "yes" to newcomers properly, then they won't be newcomers for very long - they'll be experts for most of the time they're using the language. That's why the reference manual that's clojure.org and the REPL documentation is right as it is. >Look at "([name doc-string? attr-map? [params*] body] [name doc- >string? attr-map? ([params*] body) + attr-map?])". > >Which of these characters are actually something you'd type, and which >are notations that you *don't* type? What's an "attr-map"? What's the >format for a "doc-string"? There's *nowhere* on the clojure.com site >that tells you--or even give you hints on--how to make sense of this. >I still don't know how to read it, and I've been studying Clojure for >1 1/2 years! (And by the way, I do understand a lot about Clojure; I >wrote this article: >http://pragprog.com/magazines/2010-11/getting-clojure.) > >The problem is that the entire contents of the clojure.org site is >written by an expert, for experts. To a newcomer, it says, "This is a >language for Very Smart People, who don't need any more explanation >than this. If you don't understand--well then, this language is not >for the likes of you." I agree with that - it's fundamentally a reference manual for the language, *not* a web site designed to help newcomers get started with clojure. The problem isn't the language it uses - it's exactly the right language for a reference manual. The problem is that it's the wrong content - a language reference manual is *not* where newcomers should start. The first thing newcomers should see should be motivation for why they'd want to go to the trouble to install Clojure (not the dry academic description, but the kinds of things it makes easy and quick), with a bright, obvious pointer to how to install and start using Clojure being a close second. >EXAMPLE 2: Cryptic code I'm going to skip this - there's not enough context to know if the examples were appropriate for the audience or not. >Here's what will happen: Newcomers will walk out the door if we don't >give them every encouragement to stay, if we don't actively help them >with whatever problems they experience themselves as having. Clojure >will remain this quirky little fringe language with a small oddball >(but very smart!) following, less important than R or Lua or any >number of niche languages that have reached out to the larger >programming community. > >Or... > >*You* can decide to put some effort into Clojure's *social* >excellence, as well as its technical excellence. Talk to newcomers on >*their* terms; make them feel welcome. Remember that you once had >trouble understanding things about Clojure, and frame your answers in >ways that would help the old "newcomer" you. Spend just a little time >taking one newcomer under your wing. Show them code that promotes >their understanding, right now; once they understand, show them how to >"collapse it down" into the code that dazzles. All true - but the fix is no to break the documentation we already have by dumbing it down, it's to provide documentation to help the newcomer understand what's there. And that documenation needs to be obvious on the page that loads from clojure.org. Of course, this is a minor matter as long as getting clojure running is as complicated as it currently is. But that's all part of being properly newcomer-friendly. <mike. -- Sent from my Android tablet with K-9 Mail. Please excuse my brevity. -- 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
