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

From: Jordan Schatz (jordan at noionlabs.com)
Date: Mon Dec 19 13:04:08 EST 2011

On Sun, Dec 18, 2011 at 05:19:11PM -0500, Danny Yoo wrote:
> I think you're really complaining about the following: you're not
> finding easy "next steps" to continue after the Continue tutorial.  Is
> that your understanding as well?
> 
> That would mean, not that the reference documentation is not
> necessarily badly written, but rather that there's a lack of a
> tutorial treatment of the advanced features in the library.
> 
> If that's the case, if you can point out what you think is missing
> from the story of developing Racket web apps, that would be really
> helpful for me and other potential authors.  Is there a particular
> topic that you want to understand?

I think that "Continue: Web Applications in Racket" feels like HtDP, and
therefor feels like it is an overly simplified teaching example, and not
the way I "should" go about building a "real" app. After looking at Jay's
magic 8 ball https://github.com/jeapostrophe/m8b I'm not sure if Continue
is an oversimplification or not. 

For someone who is unfamiliar with continuations, formlets, and doesn't
have a particularly good understanding of HTTP & TLS (ie SSL) I think its
a really big jump to go from "Continue: Web Applications in Racket" to
"Web Applications in Racket"
http://docs.racket-lang.org/web-server/index.html

Thats not exactly where I was, but that is where most people I am
introducing racket to are at.

Also it would be really nice to be told how one "should" develop with
racket... there is abunch of extra information that could be hidden in an
introduction to racket for experienced develops type of manual, and alot
of direction that could be given. Probably not even cover that there are
stateful servlets, and just say to use stateless ones, include how to use
a data store (db, mongo, whatever) and don't cover serializing to
disk. Suggest a directory layout and a way to organize servlets, view,
model, and controller code. Or if MVC isn't the suggested pattern, make
some other pattern explicit. 

Thanks,
Jordan


Posted on the users mailing list.