[racket] Racket documentation for web development is just awful!

From: Matthias Felleisen (matthias at ccs.neu.edu)
Date: Sat Dec 17 11:18:03 EST 2011

Dear Racket Noon, thank you for outspoken criticism. There is no question that all of our documentation and writing could be improved so that a lot more people can understand the basics. So here is a proposal: 

  write it with the help of list members here. 

Yes, there's a significant gap between introductory books such as HtDP and SICP on one hand and web docs on the other. So if someone like you could write (possibly plain) text with others here that introduces web programming on a gradual basis from these starting points, you would do a lot of people a favor and yourself the largest one -- one teaches to learn. 

-- Matthias

On Dec 17, 2011, at 11:05 AM, Racket Noob wrote:

> Dear Racketeers,
> I think I am a man of average intelligence. I have read, for example, HtDP and SICP without any major problems. Nevertheless, even with the best will, I do not understand the documentation called "Web Applications in Racket", written by Jay McCarthy (http://docs.racket-lang.org/web-server/index.html).
> I think that I'm not the only one who does not understand (and, if we look at the number of web applications written in Racket today, they can be counted on the fingers of one hand. It is a shame because Racket is a great programming language, but with poorly written and unclear documentation like this, Racket will hardly ever become popular in the web world!).
> Let's face it: Jay McCarthy is perhaps an excellent programmer and all his honor. But, as a documentation writer, this man has no idea.
> This is my well-intentioned advice to this community: let someone with more literary talent to write documentation for web development in the Racket!
> Racket Noob
> _________________________________________________
>  For list-related administrative tasks:
>  http://lists.racket-lang.org/listinfo/users

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.racket-lang.org/users/archive/attachments/20111217/5ba79fa0/attachment.html>

Posted on the users mailing list.