[racket] Racket embedding / FFI "guide" docs?

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" <jensaxel at 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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.racket-lang.org/users/archive/attachments/20110808/d86bf732/attachment.html>