<html> <head> <meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"> </head> <body bgcolor="#FFFFFF" text="#000000"> 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?).<br> <br> 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.<br> <br> 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<br> <br> > (define x (delay (+ 1 2)))<br> > x<br> promise..<br> > (force x)<br> 3<br> <br> 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.<br> <br> 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 :)<br> <br> -- caner<br> <br> [*] <a class="moz-txt-link-freetext" href="http://docs.racket-lang.org/htdp-langs/advanced.html?q=delay&q=reference">http://docs.racket-lang.org/htdp-langs/advanced.html?q=delay&q=reference</a><br> <br> [**] <a class="moz-txt-link-freetext" href="http://docs.python-guide.org/en/latest/index.html">http://docs.python-guide.org/en/latest/index.html</a><br> <br> On 01/02/2012 09:26 AM, Gerry Weaver wrote: <blockquote cite="mid:442fac90f77a855159a1efe30269c8fd@compvia.com" type="cite"> <div class="iw_mail" dir="LTR" style="font-family: Arial,Helvetica;font-size: 13px;">Hello All, <div><br> </div> <div>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. </div> <div><br> </div> <div><a moz-do-not-send="true" href="http://doc.qt.nokia.com/4.7/classes.html">http://doc.qt.nokia.com/4.7/classes.html</a></div> <div><a moz-do-not-send="true" href="http://developer.qt.nokia.com/doc/qt-4.8/all-examples.html">http://developer.qt.nokia.com/doc/qt-4.8/all-examples.html</a></div> <div><br> </div> <div><br> </div> <div>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.</div> <div><br> </div> <div>Thanks,</div> <div>Gerry<br> <br> <br> </div> </div> <br> <fieldset class="mimeAttachmentHeader"></fieldset> <br> <pre wrap="">____________________ Racket Users list: <a class="moz-txt-link-freetext" href="http://lists.racket-lang.org/users">http://lists.racket-lang.org/users</a> </pre> </blockquote> <br> </body> </html>