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

From: Jordan Schatz (jordan at noionlabs.com)
Date: Mon Dec 19 12:50:23 EST 2011

> 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

I think I've been one of the louder critics of the web development
documentation, and I also had (well still have) a frustrating time with
them. BUT Jay's an excellent documentation writer, and an excellent
programmer.

I think there is room for more documentation, I like the succinctness of
the current docs:
http://docs.racket-lang.org/web-server/index.html
http://docs.racket-lang.org/web-server-internal/index.html
and I think how much I like them will only grow as I continue to practice
developing with racket. But there is room for more of an introductory
text, not a beginner text, but something to introduce experienced
developers to some of the ideas that "Web Applications in Racket"
references.

The "cryptic" URLs is an excellent example, when I first encountered them
I thought "man this is the first thing I should volunteer to fix". I'd
been taught, and taught others in my turn, about the perfection of human
readable, unchanging URLs, that responded sensibly to get/put/post/head
requests. Now that I've read "Automatically RESTful Web Applications"
http://faculty.cs.byu.edu/~jay/static/icfp065-mccarthy.pdf and
http://faculty.cs.byu.edu/~jay/static/oopsla026-mccarthy.pdf and
http://www.cs.brown.edu/~sk/Publications/Papers/Published/pcmkf-cont-from-gen-stack-insp/
I know that there is nothing broken about the URLs and that my ideas of
what REST is where what was broken. But when I gave those papers to one
of my developers to inform him of why we where changing to ugly URLs he
thought I was off my rocker. He asked for a tutorial instead of a
research paper.

Along those lines I have started to collect notes on what developers new
to racket encounter: http://github.com/shofetim/Racket-the-Missing-Manual
please fork and help add what you think the docs need : )

Shalom,
Jordan



Posted on the users mailing list.