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