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
_________________________________________________
For list-related administrative tasks:
http://lists.racket-lang.org/listinfo/dev
