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

Reply via email to