On Thu, 16 Dec 2010 17:50:58 -0500 Stuart Halloway <stuart.hallo...@gmail.com> wrote:
> > On Thu, 16 Dec 2010 10:18:47 -0700 > > Terrance Davis <terrance.da...@gmail.com> wrote: > > > >> *begin rant* > >> > >> I have yet to see anyone who posts the classic "rtfm" (even politely) > >> response search previous posts and realize that "rtfm" responses have > >> already been sent and refrain from sending the same explanation of how > >> to use a mailing list over and over and over. Simple customer service > >> experience teaches that if customers are asking the same questions > >> multiple times, then the documentation is either, hard to find, > >> incomplete, or not clear enough. Improving the docs is a healthier and > >> more productive use of time than starting yet another thread on how to > >> use a mailing list. > >> > >> *end rant* > >> > >> Sorry. Couldn't contain myself ;-) > > > > No need to be sorry - it's a very good point. > > > > In the past, I've contributed to open source projects by watching for > > the same question to be raised multiple times, combining the data in > > the best answers into one "best of breed", and submitting it as a > > patch for the project handbook. The clojure community doesn't have > > anything as spiffy as the FreeBSD handbook - instead we have a wiki > > FAQ page (from clojure.org, click "wiki" then "2 FAQ" to get to > > http://en.wikibooks.org/wiki/Clojure_Programming). While much more > > painful than editing docbook, it's a good place to post things. > > > > Unfortunately, we can't post excerpts from clojure source there > > because the wiki license is incompatible with the source license - or > > anything else using that same license. In particular, not being able > > to use doc strings, etc. > > > > Given that the FAQ itself suggests that such be posted to the clojure > > group, this makes doing what I did rather problematical. Minimally, I > > need to figure out whether or not a post contains such an excerpt in > > order to be able to use it. Worst case, the license for content posted > > to the group is *also* incompatible with the source license, so you > > can't legally add any Frequent Answers from there to the FAQ. > > > > Ok, I found a problem. Anyone got solutions? > > > > <mike > > The new FAQ (under construction at http://dev.clojure.org/display/doc/FAQ) > has edit capabilities tied to signing the CA. > > If you have signed a CA you can post to the FAQ, quoting from other > CA-governed sources (e.g. Clojure) as makes sense. > > Does that help? First, that looks more like it's part of a wiki aimed at clojure developers than at clojure users. While that's an important thing to have, it's not what I'm looking for, and I'm pretty sure that combining the two is bad idea. Second, a wiki that requires you be a contributor to edit it seems to defeat the point of having a wiki in the first place. If you're going to require someone to be a contribute to edit the docs, why not use a real document processing system instead, so that you can handle documentation using the same tools (source control system, etc.) as you're using for code, and get the added benefit of being able to generate media-specific output (assuming you chose a good dps). Finally, Jira needs a category for "wiki bugs" so that people who haven't signed a CA can contribute fixes (patches? to a wiki? Another reason to use a real document processing system....). <mike -- Mike Meyer <m...@mired.org> http://www.mired.org/consulting.html Independent Network/Unix/Perforce consultant, email for more information. O< ascii ribbon campaign - stop html mail - www.asciiribbon.org -- 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
