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