Re: [racket-dev] documentation reorganization
I don't think you can demote either of these: The Racket Drawing Toolkit The Racket Graphical Interface Toolkit Robby On Sat, Jul 2, 2011 at 10:57 AM, Guillaume Marceau wrote: > On Fri, Jul 1, 2011 at 8:45 PM, Ryan Culpepper 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: > > This is great. > > Heres a few comments that come to mind: > > Underneath the "Teaching" header, the first item is "How to Design > Programs", it should probably read "How to Design Programs, the Book". > > RackLog should be under "Languages" or under "Experimental Languages", > not under "Tools". > > I am nominating RackUnit for promotion to the "Racket Language and > Core Libraries" section. I would demote "drawing toolkit" if you don't > want the section to get any larger. As it is, there are two items that > make the sales pitch "we can draw things in windows", but none that > say "we take testing seriously". > > The racket/gui manual should have a duplicate entry under "GUI and > graphics libraries". > _ > For list-related administrative tasks: > http://lists.racket-lang.org/listinfo/dev > _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] documentation reorganization
On Fri, Jul 1, 2011 at 8:45 PM, Ryan Culpepper 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: This is great. Heres a few comments that come to mind: Underneath the "Teaching" header, the first item is "How to Design Programs", it should probably read "How to Design Programs, the Book". RackLog should be under "Languages" or under "Experimental Languages", not under "Tools". I am nominating RackUnit for promotion to the "Racket Language and Core Libraries" section. I would demote "drawing toolkit" if you don't want the section to get any larger. As it is, there are two items that make the sales pitch "we can draw things in windows", but none that say "we take testing seriously". The racket/gui manual should have a duplicate entry under "GUI and graphics libraries". _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] documentation reorganization
Yes, I understood you. I'm observing that making it plural is not helping. On Fri, Jul 1, 2011 at 9:06 PM, Eli Barzilay wrote: > Three minutes ago, Robby Findler wrote: >> On Sat, Jul 2, 2011 at 9:53 AM, Eli Barzilay wrote: >> > Four minutes ago, Robby Findler wrote: >> >> On Sat, Jul 2, 2011 at 9:41 AM, Ryan Culpepper 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. >> > >> > I also prefer the plural title, as a signal that "more might be >> > here" rather than singular, which begs a question of "why bother >> > with a category for it". >> >> That's not what "begs the question" means and that's not what plural >> means, either. > > By "signal" and "begs" I meant that that's what it leads me to think. > In other words (and IMO) "low-level APIS" makes sense as a container > for more than a single entry so the fact that there is one looks like > more will be there. On the other side, having just one entry with a > singular title raises the same kind of question I'd have if I read a > book with "Chapter 1" but no other chapters. > > -- > ((lambda (x) (x x)) (lambda (x) (x x))) Eli Barzilay: > http://barzilay.org/ Maze is Life! > _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] documentation reorganization
Three minutes ago, Robby Findler wrote: > On Sat, Jul 2, 2011 at 9:53 AM, Eli Barzilay wrote: > > Four minutes ago, Robby Findler wrote: > >> On Sat, Jul 2, 2011 at 9:41 AM, Ryan Culpepper 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. > > > > I also prefer the plural title, as a signal that "more might be > > here" rather than singular, which begs a question of "why bother > > with a category for it". > > That's not what "begs the question" means and that's not what plural > means, either. By "signal" and "begs" I meant that that's what it leads me to think. In other words (and IMO) "low-level APIS" makes sense as a container for more than a single entry so the fact that there is one looks like more will be there. On the other side, having just one entry with a singular title raises the same kind of question I'd have if I read a book with "Chapter 1" but no other chapters. -- ((lambda (x) (x x)) (lambda (x) (x x))) Eli Barzilay: http://barzilay.org/ Maze is Life! _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] documentation reorganization
On Sat, Jul 2, 2011 at 9:53 AM, Eli Barzilay wrote: > Four minutes ago, Robby Findler wrote: >> On Sat, Jul 2, 2011 at 9:41 AM, Ryan Culpepper 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. > > I also prefer the plural title, as a signal that "more might be here" > rather than singular, which begs a question of "why bother with a > category for it". That's not what "begs the question" means and that's not what plural means, either. (But perhaps I'm old fashioned.) Robby _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] documentation reorganization
On Fri, Jul 1, 2011 at 9:41 PM, Ryan Culpepper wrote: > re "misc": Do you mean "Other"? Would you prefer "Other Languages and > Libraries" or "Other Manuals"? I think those should just go under "Experimental Languages", since they're both languages, and at least one is experimental. -- sam th sa...@ccs.neu.edu _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] documentation reorganization
Four minutes ago, Robby Findler wrote: > On Sat, Jul 2, 2011 at 9:41 AM, Ryan Culpepper 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. I also prefer the plural title, as a signal that "more might be here" rather than singular, which begs a question of "why bother with a category for it". -- ((lambda (x) (x x)) (lambda (x) (x x))) Eli Barzilay: http://barzilay.org/ Maze is Life! _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] documentation reorganization
On Sat, Jul 2, 2011 at 9:41 AM, Ryan Culpepper 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 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
Re: [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 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
Re: [racket-dev] documentation reorganization
Great stuff. This is a big improvement.
Carl Eastlund
On Fri, Jul 1, 2011 at 8:45 PM, Ryan Culpepper 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
Re: [racket-dev] documentation reorganization
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 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
Re: [racket-dev] documentation reorganization
I think the 'guide' and 'reference' links could use a description of
what they are similar to the tutorial links.
On 07/01/2011 06:45 PM, Ryan Culpepper 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
