[racket-dev] documentation reorganization

On Sat, Jul 2, 2011 at 9:41 AM, Ryan Culpepper <ryan at cs.utah.edu> 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<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
>>>
>
>