On Wed, Sep 19, 2012 at 1:12 AM, Andy Fingerhut <andy.finger...@gmail.com> wrote: > On Tue, Sep 18, 2012 at 9:01 PM, Paul deGrandis <paul.degran...@gmail.com> > wrote: >> >> 1.) Clojure.org should have a better host of documentation, especially for >> newcomers. > The only things required for someone to create a new web site dedicated to > better Clojure documentation is time, knowledge, and some money.
There are several intermingled issues: 1. People want to feel involved. Its the opposite of "founding" a new project, on your own. That their modest effort will be seen by others, since its a part of this bigger thing. Contributing to clojure.org versus your own personal project are 2 different things. 2. Clojure.org isn't sharing traffic, or google juice.. its a walled garden. Leiningen doesn't come up in the first 5 pages of google search results, for example. If a newbie can't find Leiningen, how are they gonna find my project? 3. People want clojure to be taken seriously, and want a public face that is "in the same league" as other popular languages, by whatever standards that entails. 4. Clojure.org hasn't evolved much, meanwhile the technology and the community have evolved a ton. That is a vacuum liable to be filled with opinionating. There is a cognitive dissonance there, and people want to resolve it somehow. 5. People are confused about what the purpose of clojure.org is. AFAICT it is a reference guide to the efforts of clojure/core. In that context, not including a reference to Leiningen makes sense. But people are confused if that is a suboptimal oversight, or a conscious decision. 6. People are disturbed by the "no-handholding" style of 3rd party libraries, and see it as a systematic problem in the community. The figurehead is the obvious focal point of this anxiety. Appropriately so, since it plays a big role in the community culture. So there are many dimensions to play in, to empower/mollify. If you've read this far I highly recommend going back to the survey results and analysis. Some strong words, and strong quantitative measures. http://cemerick.com/2012/08/06/results-of-the-2012-state-of-clojure-survey/ "I didn’t think it possible, but an even larger proportion of respondents than last year — now up to a third — indicate that documentation is a key problem. This ties into the feedback seen earlier that library documentation is generally not what it should be. To a large degree, this is a self-inflicted wound: both Clojure and its libraries are technologically sufficient and effective and useful, but many, many people are tripping on their way towards using them. Given that the only other problems within 10 percentage points of the documentation issue are largely out of everyone’s direct control [...] the best thing anyone can do to help Clojure succeed is to help make documentation and tutorials better for every skill level and domain, anywhere. I do what I can in my projects and elsewhere; please do what you can, too." -- 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
