[racket-dev] Racket documentation

Everett, thanks for your comments. I think they are right on: 

On Sep 21, 2010, at 3:14 PM, Everett Morse wrote:

>  I’m sure if you understood Racket well it would all make sense, but it does not help a beginner get better
> 

You may not believe this, but even someone who has programmed in Racket for 15 years and in DrRacket for 13 of them, the API docs are still quite cryptic :-) 

> What PHP Does
> 

I like what you describe. Most or possibly all of what PHP provides should come with Racket too. 

Here's our problem. We need manpower to get from where we are to where we should be. Here is what I see could happen: 

1. Scribble our doc language needs some escape hatch into a wiki. I think Eli has thought about such things and others probably, too. The web server is in Racket, so that's taken care of. 

2. The existing docs have a huge advantage over everyone else's docs. I am sure you know that. So the challenge is to integrate (1) with the existing Docs. Not a big deal and doable. 

3. The sources, including docs, are all out there. Take them. Change the layout. Equip each function/method page with a user-wiki-thingie. Collect suggestions, appoint editors, edit the suggestions into the doc pages. 

4. There's no need to host this internally initially. When the thing is off the ground, we integrate it and -- minus the wiki -- localize it. The wiki becomes a link to the on-line version of the docs (corresponding page) and then users who find they have something to contribute are one click away from doing so. 

I think this is a wonderful project that non-core PLTers can run and they would make a huge contribution to the language and community that way. 

;; --- 

> With Racket, no short tutorial is going to work because it has a LISP (and Scheme) functional programming background that is foreign to most new programmers and many experienced ones.

And that's the reason I welcome your ideas so much. It is possible to program in a Lisp-style language as if you were in C plus parens. Hey we have for/do and if and assignment statement, and we have classes. But yes, you'd lose a lot if you adopted this style. It wouldn't make sense to run things that way. But the API idea is fascinating. 

Someone step forward and pick it up. We'd welcome it. Thanks for such a wonderful idea -- Matthias




-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.racket-lang.org/dev/archive/attachments/20100921/b00917ca/attachment.html>