<p>I'm not saying that the docs are perfect, but not-being-another-wiki is, to me, a feature.</p>
<p>Deren</p>
<div class="gmail_quote">On Aug 7, 2011 8:05 AM, "Jens Axel Søgaard" <<a href="mailto:jensaxel@soegaard.net">jensaxel@soegaard.net</a>> wrote:<br type="attribution">> User contributions are what is needed to improve the documentation.<br>
> <br>> 1. It should be *easy* to report spelling errors and/or complaints<br>> about a particular page.<br>> <br>> 2. There should be a discussion section on the bottom of each page.<br>> <br>
> Solving 2) is easier than one might think. Disqus is a site that<br>> hosts discussion threads. A thread is is embedded into a page<br>> with a piece of with JavaScript. When the page is loaded the<br>> comments are fetched in the background. Each discussion thread<br>
> gets its own id. This means that even though the documentation are<br>> generated and stored locally the same thread is loaded and shown for<br>> everyone. ( <a href="http://docs.disqus.com/help/14/">http://docs.disqus.com/help/14/</a> )<br>
> It also means that is possible to associate a discussion thread<br>> to, say, each page or function, and to keep the dicussion thread<br>> in the event the documentation is rearranged.<br>> <br>> <br>> Why are user contributions needed? Well, Danny's Reddit example show<br>
> valuable user feedback is lost. Perhaps not from the mailing list<br>> regulars but from the more casual users.<br>> <br>> The redditor in question complained about the lack of examples<br>> in the Racket documentation, and only after prodding revealed<br>
> it was the embedding section he based his opinion on.<br>> Finding such weak spots are difficult with some *easy* way<br>> for users to leave feedback.<br>> <br>> I saw the discussion on Reddit too.For those that didn't someone<br>
> didn't like the Racket documentation. It lacked examples, he said.<br>> After some prodding it was revealed that it was the section on<br>> embedding in particular he didn't like.<br>> <br>> Lately I have read the jQuery (a JavaScript library) documentation.<br>
> <br>> Each function gets its own page. On every(!) page below the main text<br>> they have a small paragraph reminding people to ask question on the<br>> mailing list and/or irc. Then comes a Disqus discussion and comments<br>
> sections, where users can discussion the<br>> <br>> See <a href="http://api.jquery.com/css/">http://api.jquery.com/css/</a> for a concrete example.<br>> Note the proportion of examples. It is interesting to see<br>
> that such a page has 58 (!) comments.<br>> <br>> Now since Racket has a mind-boggling number of functions,<br>> I am not suggesting that this style should be adapted, but<br>> adding a discussion section would be a good move.<br>
> <br>> <br>> Back to the guy on Reddit. He had a bad experience with<br>> the documentation, but (presumably) never reported it.<br>> Maybe he would "Report a bug" link on each page<br>> encourage more feedback?<br>
> <br>> <br>> -- <br>> Jens Axel Søgaard<br></div>