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
