[racket] Isn't the web application tutorial too advanced?

On Mon, Apr 28, 2014 at 5:27 AM, Ben <yfefyf at gmail.com> wrote:
> After gaining some basic understanding of web applications, I wanted to
> develop one in Racket. So I went to the tutorial "Continue: Web Applications
> in Racket". When I reached "6 Advanced Control Flow", I saw
> `send/suspend/dispatch`. I didn't know what it is, so I clicked on the link
> to see its documentation and saw a very complex starting sentence:

Hi Ben,


Apologies for not responding to this in a timely way.

It sounds like you saw the link to the reference documentation, took a
depth-first approach, and then got stuck in the reference
documentation, which is not beginner friendly.  Does this evaluation
sound accurate to you?


If so, perhaps we should redirect links so that beginners are not
directed to the reference documentation.  Perhaps links to functions
in the tutorial documentation should go to some of glossary that is
appropriate to a tutorial, rather than directly to the reference
documentation.  I am not sure what the right approach is.


There is a paragraph that is in the Advanced Control Flow section that
is intended to hand-wave the explanation of what that function is
doing:

"Let’s look more closely at the send/suspend/dispatch
mechanism.send/suspend/dispatch consumes a response-generating
function and gives it another function, called embed/url, that we’ll
use to build special URLs. What makes these URLs special is this: when
a web browser visits one of them, our web application restarts, not
from start, but from the handler that we associate with the URL. In
the handler phase-1, the use of embed/url associates the link with the
handler phase-2, and vice versa."

Would it have helped if we were to move that paragraph up closer to
where we first mention send/suspend/dispatch?