[racket] Documentation enhancement suggestions

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






-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.racket-lang.org/users/archive/attachments/20120102/4119b6e7/attachment.html>