On Mon, Apr 28, 2014 at 5:27 AM, Ben <yfe...@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? ____________________ Racket Users list: http://lists.racket-lang.org/users