[racket-dev] Racket documentation

Jay McCarthy wrote:
> What do you think is missing from these tutorials:
> 
> http://docs.racket-lang.org/quick/index.html
> 
> http://docs.racket-lang.org/continue/index.html
> 
> http://docs.racket-lang.org/more/index.html
> 
> In particular, Quick tries to present the essence of the languages.
> Maybe the problem is that since we are PL researchers, we have a more
> refined opinion about the "language" versus the "libraries" so our
> tutorials don't go too deep in the libraries.

We like languages and libraries factored so we can reason about them in 
isolation; users like them integrated so they can understand how they're 
used together. OTOH, with hygienic macros, all languages but the kernel 
language are libraries anyway, so maybe we should stop fooling ourselves 
that there's a well-defined difference in the first place. :)

> We need more examples in the docs. It's easy to add them and I will
> help anyone who wants to get involved.

I agree with Matthias that this is something best done by non-core 
developers. I think it would be great to have some of it done by 
trustworthy casual users as well. How hard is it to give easy access to 
docs for the most basic functions without giving access to the source 
itself? I imagine these (along with I/O and other peripheral libs 
necessary for solving ``real'' problems) would be the most important to 
flesh out.

Is there a way to reduce the barrier so far that you don't even have to 
check out and compile Racket to contribute to the docs? And additionally 
not have to remember very much to remember how to do it?

>> It lists related functions. You may be looking for something similar to the
>> function you found. This listing helps you compare similar functions and
>> hone in on the one you really want.
> 
> This is a good idea, but I think it is a symptom of the one-page per
> function, whereas in Racket they are listed together with related
> ones.

I think they should stay that way. Interaction among functions is too 
important to put a click barrier on. Separating them would be like 
putting each method doc on a different page for an OO library.

>> Occasionally it warns (with appropriate font and colors) about common
>> gotchas, like when something has changed from one API version to another
>> (e.g. a function now returns false on failure instead of -1), or when some
>> environment needs to be set up right (e.g. setting a timezone before calling
>> the date function, it even tells you what function sets the timezone).
> 
> See above with the ad-hoc grossness of PHP.

I agree it's less ad-hoc in general, but it *would* be nice to have a 
uniform way to indicate functionality *extensions*. ("Hey! Two versions 
ago, we added an optional 'bip' argument to 'bop'!" Or "You should 
really consider using scale/improve-new-text in place of scale in general.")

---

One thing I'd like to see institutionalized is having two different 
descriptions: a "high-level" one, and a "here's the nitty-gritty 
details" one. I've been put off using functions before because of those 
details, especially functions that deal with syntax. Later I found out 
that the function was exactly what I needed. Even later I found out that 
the detail was extremely important in solving a problem in an important 
common case. The whole thing could have gone a lot faster with two 
descriptions.

I know that would happen somewhat if there were always examples, but it 
wouldn't guarantee it.

Neil