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

From: Gerry Weaver (gerryw at compvia.com)
Date: Sun Dec 18 00:51:11 EST 2011

Hi Noob,

I'm very new to Racket and the community as well. I happen to agree that the web development docs could use some improvement. However, I'm not sure tweaking the one person that is in the best position to help you is wise. Further, from what I have seen so far, Jay is very objective in the way that he handles things like this. I find the Racket community to be very refreshing in general and it disappoints me to see a post that is worded the way yours was. I think it is important to remember that folks like Jay are giving us the benefits of their hard work for free. If your not in to writing some docs (as someone suggested), perhaps your questions could have been "How do I get started?" or "This is what I've got so far, can y'all help me move forward?".  I think you will find that if you just start walking, people will help you along the way. I don't think it is necessary or productive to
call someone out. We should just be thankful that we have Racket and any docs for it at all.

Just my .02

Thanks,
Gerry

-----Original Message-----
From: "Racket Noob" <racketnoob at hotmail.com>
To: users at racket-lang.org
Date: 12/17/11 10:06
Subject: [racket] Racket documentation for web development is just awful!

 
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/7454a584/attachment.html>

Posted on the users mailing list.