[plt-scheme] please help us scribble!

The three most important improvements in PLT Scheme v4 will be:

 1. documentation (better organized)

 2. documentation (more readable "guides" and examples)

 3. documentation (better integration with tools like DrScheme)

There are also some languages changes, such as the library
reorganization and keyword arguments, but mostly those are in the
service of better documentation.

The new core documentation is starting to come together. The
`scheme/base', `scheme', and `scheme/gui' languages are fairly
thoroughly documented, for example, as are Scribble itself, the FFI,
and Inside PLT Scheme. We have plenty of work to do on the guide, but
that can improve and evolve after we get the reference documentation in
place.

One big remaining task is all of the "doc.txt" files --- former
second-class citizens that need to ported as fully fledged, scribbled
parts of the PLT documentation. We have considered trying to fit
"doc.txt" files into the new documentation system, but it's awkward.
Anyway, we want *good* documentation for everything, and that means
scribbling it.


We could use your help scribbling "doc.txt" files!

See

  http://www.cs.utah.edu/~mflatt/tmp/doc-to-do.txt

for a list of things to be done. This is not a complete list; it's a
list of documents that could easily be ported by someone other than the
authors of the relevant libraries (who are either no longer active or
have plenty of other documents to port).


Here's how you can help:

 * Pick a document (some are easier than others) that doesn't yet have
   a name next to it, and send mail to claim it as your responsibility.

   I recommend replying to this message and keeping the plt-scheme list
   cc'ed, but if you're a bit shy (I would be), you can send mail
   directly to me, and I'll quietly add your name next to a choice.

 * Read the Scribble manual:

     http://pre.plt-scheme.org/docs/html/scribble/

   Chapter 1 will get you started, but you'll likely need to read
   through Chapter 3. Pay attention to the style guide at the end of
   Chapter 1:

     http://pre.plt-scheme.org/docs/html/scribble/
     How_to_Scribble_Documentation.html#(part~20reference-style)

   There are lots of examples in the "scribblings" collection, which is
   where the core doc sources reside.

 * Port the "doc.txt" to "doc/manual.scrbl". You can call
   "manual.scrbl" whatever you want, but "manual.scrbl" is a good
   default, especially for single-file sources. Use multiple files
   (with `include-section') if you think it's appropriate.

   You'll need an "info.ss" file in your "doc" sub-collection so that
   `setup-plt' will build the document. See "mrlib/doc/info.ss" for an
   example.

 * Re-read the style guide after you've scribbled. Probably you'll
   notice things the second time around that affect the text that you
   wrote or ported.

 * E-mail me your scribblings as "doc.tgz" or "doc.zip". I will likely
   edit for content and style, but you will have saved us a huge amount
   of time by getting it mostly in shape --- and thus help get v4 out
   the door sooner.

Your reward will be a hearty "thanks!" from the PLT Scheme community, a
place in an acknowledgments section, and the satisfaction of knowing
that you've done your part.

Longer term, we welcome contributions in the form of high-level
explanations and examples to complement the reference documentation.
For now, moving over the old documentation is our most pressing need.

Thanks,
Matthew