On Jun 13, 10:58 pm, Sean Corfield <seancorfi...@gmail.com> wrote: > On Wed, Jun 13, 2012 at 7:45 PM, Sean Corfield <seancorfi...@gmail.com> wrote: > > We definitely need improvements in the official getting started > > documentation. Starting here - > >http://dev.clojure.org/display/doc/Getting+Started- any specific > > problems / improvements that folks identify will generally get fixed > > fairly quickly if they're brought up on this list. There are a couple > > of list members who are pretty motivated around improving the "newbie > > experience"... > > And of course the official clojure-mode and swank-clojure > documentation *is* on Github so fork/update/pull request is the > natural workflow there. > > The information in the comments > onhttp://dev.clojure.org/display/doc/Getting+Started+with+Emacsneeds to > be folded into the main instructions (and the comments deleted, IMO, > since they just add to the noise and confusion). > > The page should start with links to install the current stable version > of Emacs for Windows, Linux, Mac. The latest version of swank-clojure > should be referenced (1.4.2).
It's difficult to keep wiki docs nice and up-to-date. Writing good (and concise) docs is hard work. Some potential contributors may not want to go through the time to register and send in the CCA (or whatever the confluence wiki requires). Others may not want to take the time to contribute a magnum opus to the wiki because they're not crazy about the idea of someone coming around after them and making sweeping changes to their work. I know I like to keep my own magnum opi sequestered off in my own docs directory (for example, http://www.unexpected-vortices.com/clojure/10-minute-emacs-for-clojure.html ). Wiki's have a tendency to become cluttered and disorganized. Same with individual wiki pages, for that matter. A great strength of wikis is that there's a lot of eyeballs that can (or should be able to) easily fix typos & broken-links, update out-of- date links, and so on. IMO: * core docs should be a focused set of .md files that contributors work on by cloning, editing, and sending pull-requests. * wiki docs should be easy to contribute to and should encourage links to outside docs (though, include last-modified dates for those!). Users can sort out which external articles and blog-posts are most useful, which can then "bubble to the top", so to speak. Just my 2¢. ---John -- 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
