[racket] Documentation enhancement suggestions

I don't like the idea of people solving "real world" problems
copy/paste'ing code from docs, which I'm not sure it's even possible
(e.g. what would be the example of call/cc?).

However, couple of times I've been in a position to write some general
usage examples of a function that we looked up in a class with students,
where I was also demonstrating an example usage of the docs itself.

For example, for 'delay' and 'force' to generate streams, we look up the
language reference where the lang was advanced student[*]. Then I felt I
need to write

> (define x (delay (+ 1 2)))
> x
promise..
> (force x)
3

on the board. I think if there were some kind of automation where we can
provide some examples for any 'non-exampled' constructs that we see in
docs, it would increase the enhancement of the docs. However, it would
somehow require moderation, which of course in some cases would be a
real pain.

To generalize this, it would be great to have something like "The
Hitchhikers Guide to Racket!", like [**], but I don't really have a
single clue how to do that :)

-- caner

[*] http://docs.racket-lang.org/htdp-langs/advanced.html?q=delay&q=reference

[**] http://docs.python-guide.org/en/latest/index.html

On 01/02/2012 09:26 AM, Gerry Weaver wrote:
> Hello All,
>
> It seems we are not seeing many/any actual suggestions for ways to
> improve the Racket documentation. I have been thinking about this
> quite a bit. Writing good documentation is hard and very time
> consuming. It is also a task which most developers absolutely hate
> (myself included). I've been trying figure out what could be done that
> would hopefully minimize the pain and shorten the timeline to
> enhancing the docs. I think the area that could most use the attention
> would be the library reference. If each library function were to
> include a practical (not contrived) real world usage example, it would
> help a lot. The Nokia Qt library would be a good example of what I'm
> talking about. In most cases the docs contain usage examples that are
> further augmented by nice collection of working code examples. I am
> not suggesting that Racket should do a knock off of Qt's docs or
> anything like that. I use Qt as an example, because the Qt docs are
> generally regarded as some of the best out there. When I say "real
> world" examples, I mean that they are written with the idea that the
> developer can copy and paste them into his/her code as a good starting
> point. Since the web docs were the original issue, I would suggest
> something similar. A few example web applications that represent
> typical use. For example, a restful web service with ajax, an xmlrpc
> service, and template based pages would be a good start. These example
> apps should include sessions, cookies, SSL, and be backed by a
> database of some sort. They should also include a text that provides a
> line by line walk-thru of the code. Most of the popular web frameworks
> out there have these types of examples. 
>
> http://doc.qt.nokia.com/4.7/classes.html
> http://developer.qt.nokia.com/doc/qt-4.8/all-examples.html
>
>
> Disclaimer: I'm not trying to be critical or ruffle any feathers. My
> intention is only to put a stake in the ground as a starting point.
>
> Thanks,
> Gerry
>
>
>
>
> ____________________
>   Racket Users list:
>   http://lists.racket-lang.org/users

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.racket-lang.org/users/archive/attachments/20120102/87b37bdc/attachment.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 554 bytes
Desc: OpenPGP digital signature
URL: <http://lists.racket-lang.org/users/archive/attachments/20120102/87b37bdc/attachment.sig>