[racket-dev] documentation reorganization

Great stuff.  This is a big improvement.

Carl Eastlund

On Fri, Jul 1, 2011 at 8:45 PM, Ryan Culpepper <ryan at cs.utah.edu> wrote:
> 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