[racket-dev] documentation reorganization

I just pushed a commit intended to improve the usability of the main
documentation page, especially for newcomers to Racket. You can also
see the new version here:

   http://www.cs.utah.edu/~ryan/tmp/doc/

If you have a manual in the trunk, I probably changed it
slightly. Take a look at the changes. The rest of this message is
about the rationale behind the reorganization.

--

Back in May, we heard from a newcomer to Racket who had gotten lost in
the documentation and ended up going down the wrong path. His report
sparked a discussion about, among other things, changing the
documentation to make it more accessible to newcomers and
visitors. While there are some gaps in the content of the
documentation we have available, the primary problem seemed to be the
organization; the newcomer didn't find the right manuals to read.

The new documentation has four conceptual parts: Orientation, Racket,
Teaching, and Everything Else.

Orientation: The Getting Started link now stands alone; previously it
was too easy to miss. The tutorials are now labeled as such in a
separate section.

Racket: The previous organization was too egalitarian. The Racket
Reference was bare centimeters above the R6RS manual; R6RS is the
standard, right?---guess I should start there! Core libraries were
scattered throughout the documentation; you have to scroll to find the
GUI manual.

The new "Racket Language and Core Libraries" section makes it clear
where the serious, comprehensive material about Racket starts. The
core libraries are part reassurance ("good, there's a standard GUI
toolkit") and part advertisement ("oh, there's a standard way of
producing documentation").

Teaching: The teaching materials are important enough to the Racket
mission that they come next.

Everything Else: There are a couple lesser improvements to the rest of
the manuals.

First, the old "Languages" section (again, overly egalitarian) is now
much smaller, and its role is clarified. Racket is The Language; these
are others... what does that mean? The link explains it.

Second, I've done away with the "@bold{X}: Y" manual naming
convention. In some cases this convention works, but in most cases it
was a poor fit. "@bold{Guide}: Racket" is a bit inscrutable compared
to "The Racket Guide", and "@bold{Version}: Racket Version Checking"
is grandiose for a manual that documents eight exports. The convention
was confining, and it led to an arms race of bolding. If your manual
didn't start with a bold keyword, it looked pitiful. I've changed
major manuals to have names such as "The Racket Guide", "The Racket
Drawing Toolkit", etc. I've renamed a few other manuals in that style,
such as "Web Applications in Racket" (used to be "Web: ...") and
"Extending DrRacket" (used to be "Plugins: ..."). Use the unbolded
"X: Y" pattern for manuals that are just the documentation for some
collection; otherwise consider giving the manual a more descriptive
name.

--

This is intended as a first step. In particular, I wanted to get the
first three parts (Orientation, Racket, Teaching) in better shape in
time for the upcoming release.

Ryan