Stu--- Thanks for the links. I took a look at clojure dev and signed up. I don't see any way to edit----does that happen after I mail in the Contributor agreement? It does seem a little medieval to have to mail it in.
Clojure dev though doesn't seem like such a direct way of improving clojure.org, which is what people see and try to use. (Steve, ClojureDocs.org is also another outside site.) The fact that people are posting tutorials in blog posts that need to be corrected as the language changes strikes me as an indication that there isn't enough of a way for them to write these things under Clojure's aegis. Why not eventually make a "beta" version of Clojure.org (with the exact same formatting), that can then be migrated piece-by-piece to the main site as things get approved----and let anyone edit this, wiki- style? What's there on clojure.org is already quite good (with the exception of Getting Started, which still tells people to do "java - cp ...."). There could also be someone responsible overall for each section, so it doesn't get too messy a la the Emacs Wiki. I'm happy to put some time into organizing the API a little better, but I don't see any way of doing this at the moment. (I see no API section on Clojure dev.) I'd love to see the API reference not only organized into good groupings with cross-references from a given function (one area where OOP actually \is a good thing----the only one, so far as I can tell), but have these groupings include references to related Contribs and even Java functions with their Clojure call syntax. So long as there is a way for users to add these sorts of things, it can grow over time. There is probably a way of automatically snarfing things from JavaDocs as well. Again, I'm happy to undertake this sort of project, but I need to see if it's a good idea, and I obviously need guidance. Why not have clojure.org also include tutorials (the equivalent of Java trails, perhaps) to get a given thing done: shell scripting; web server; system programming; Swing; etc. The best of what people put on blogs could go straight on the main site, and then be kept up to date right there. Once this is done, you might actually get people up to speed on Clojure fairly quickly. Best, Nick. On Jul 7, 6:12 am, Stuart Halloway <stuart.hallo...@gmail.com> wrote: > > It may be that I am really talking about the website (clojure.org, not > > any of the auxiliary ones, which are a bit of a mess in themselves) > > more than the language itself. If people receive the \right > > instructions, setting up Emacs/Leiningen/Web servers etc. is actually > > not so hard. The trouble is that all of this information is currently > > scattered to the four winds (I include things like the Paredit cheat > > sheet, Slime commands, which Emacs to use, etc.), and I don't think we > > should rely on users to pull this information together themselves---- > > and at any rate, why should they? > > "Getting Started" documentation is bound to be a high churn area. Here are > things you can do to help: > > (1) Edit and improve the official > docs:http://dev.clojure.org/display/doc/Getting+Started > > (2) Link to the official docs, and help us do the same. clojure.org has a > slower update process than the dev site (by design!) but if there is > something wrong, or a place where it needs to link out, please let us know! > > (3) Encourage people who wrote a blog post 18 months ago that is now filled > with misinformation (as things have moved on) to go back and add a link to > the official docs. > > There are now almost 300 signatories to the contributor agreement, and any of > them can update dev.clojure.org without any review process. This should be > plenty of horizontal scaling to keep documentation (even high-churn > documentation) accurate. > > Thanks to everyone who is helping out! > > Stu > > Stuart Halloway > Clojure/corehttp://clojure.com -- 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
