Hey Niel, I'm not your enemy (just annoys me that do not understand anything), but poor documentation surely is.
Regarding this "big and complicated thing": the Windows API, for example, is ugly and complicated. Yet, legendary Charles Petzold managed to write a very readable and clear book about it. (Oh, if only we could convince Petzold to write a nice book about web development in a Racket! :))
Of course, I cannot write better documentation because i don't have a clue, but I hope that I can at least express my opinion that this current is not good. And i think this is one of the main reasons for poor use of Racket in the web (otherwise, Racket is just great!).
Date: Sat, 17 Dec 2011 12:06:54 -0500
From: neil at neilvandyke.org
To: racketnoob at hotmail.com
Subject: Re: [racket] Racket documentation for web development is just awful!
Racket Noob wrote at 12/17/2011 11:05 AM:
and, if we look at the number of web applications
written in Racket today, they can be counted on the fingers of one hand.
There's at least a few more than that. Some Racket developers are
secretive.
Regarding the topic of your message, consider that you are reading the
*reference manual* for something that is big and complicated. As you
know, the first priority of a reference manual is to capture technical
information, not to gently instruct in usage, nor to be fun to read.
Perhaps, as Matthias suggested, you would write one of the usage
documents, based on what you're learning and on your prior experience?
--
http://www.neilvandyke.org/
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.racket-lang.org/users/archive/attachments/20111217/26c761c6/attachment.html>