This looks great to me. Minor thing: "Low-Level APIs" => "Low-Level API" and the last section actually can have a name other than "misc" I think.
Robby On Sat, Jul 2, 2011 at 8:45 AM, Ryan Culpepper <r...@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 > _________________________________________________ > For list-related administrative tasks: > http://lists.racket-lang.org/listinfo/dev > _________________________________________________ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
