On Sat, Jul 2, 2011 at 9:41 AM, Ryan Culpepper <[email protected]> wrote: > re "Low-Level API": the other category labels are generally plural, and > other manuals might get inserted into this category (eg by planet packages)
The page is regenerated when new manuals are added, no? Just make it plural then. > re "misc": Do you mean "Other"? Would you prefer "Other Languages and > Libraries" or "Other Manuals"? At the moment it contains two "experimental" languages so "other" seems like a bad title. Robby > Ryan > > > On 07/01/2011 06:51 PM, Robby Findler wrote: >> >> 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<[email protected]> 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
