[racket-dev] documentation reorganization

re "Low-Level API": the other category labels are generally plural, and 
other manuals might get inserted into this category (eg by planet packages)

re "misc": Do you mean "Other"? Would you prefer "Other Languages and 
Libraries" or "Other Manuals"?

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