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

Let me react just to what's being said here, though I am not familiar 
with any of the documents mentioned.

I've found that what's often missing in documentation written by 
programmers is that it's too nose-to-the-ground.  Once you understand 
what's going on, it's excellent in telling you the details that you 
have to know to use it. But until you have that global understanding, 
you're lost.  Is this what's going on here?  All tactics and no 
strategy, so to speak?

It is quite difficult to write good overview documentation.  The 
programmer tends to be so familiar with the software that he lacks the 
level of ignorance and misunderstanding the newbie brings to the 
subject.  This makes it very difficult to see what needs to be written.

I recall the excellent manuals published by IBM way back in the 60's 
for their OS/360 series.  Each significant system component had two 
separate manuals.

One was called "Concepts and Facilities", which explained how to use 
the various system calls in concert to achieve common ends.  No, it 
didn't consist of code examples (though they were there); it consisted 
primarily of explanations in English, with snatches of code to look 
at when you wanted to see the details.  The snatches were just 
snatches.  In a section about reading files, they contained only the 
pieces actually involved in reading files, not anything resembling a 
runnable application.  The English text explained the order in which 
they had to be called, how they interacted, when you had to allocate 
buffers and free them, how you had to do it, and so forth. 

The other was called "Reference Manual" and contained, system call by 
system call, its complete, precise description, all its mandatory and 
optional parameters, and so forth.  Incomprehensible if you hadn't read 
the "Concepts and facilities" section first.

This reply may not help you.  But it might structure discussion, so 
we'll get an idea what's lacking that you need.

Or not.

-- hendrik

On Sat, Dec 17, 2011 at 05:37:32PM +0100, Racket Noob wrote:
> 
> 
>  I've already read. Continue tutorial is not bad, I passed through it (congratulations, Danny Yoo, you're man!)
> But now when I want to make the next step and further understand the web development in Racket, unfortunately I am forced to read Jay's documentation. I am very sad about it. : (Unfortunately, in this case I find it difficult to give any constructive criticism, I do not know even where to start. Maybe a question for the end: Do the URLs of pages that use continuation mechanism have to look ugly and cryptic? Can this somehow be avoided (so that we have pretty URLs, but still have a continuation?)  Racket Noob  > From: samth at ccs.neu.edu
> > Date: Sat, 17 Dec 2011 11:18:06 -0500
> > Subject: Re: [racket] Racket documentation for web development is just awful!
> > To: racketnoob at hotmail.com
> > CC: users at racket-lang.org
> > 
> > First, I want to encourage you to take a look at the "Continue"
> > tutorial: http://docs.racket-lang.org/continue/ . It provides an
> > excellent introduction for people new to the Racket web server.
> > 
> > Second, one of the great things about Jay is that in addition to the
> > video game talent and popped collars, he's very responsive to
> > suggestions.  If you have specific things that could be explained
> > better, I'm sure he'd be happy to hear about them.
> > 
> > Finally, while we all appreciate feedback, personally insulting people
> > isn't appropriate in this context.
> > 
> > 2011/12/17 Racket Noob <racketnoob at hotmail.com>:
> > >
> > > 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
> > 
> > 
> > 
> > -- 
> > sam th
> > samth at ccs.neu.edu
>  		 	   		   		 	   		  

> _________________________________________________
>   For list-related administrative tasks:
>   http://lists.racket-lang.org/listinfo/users