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
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 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
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 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
Re: [racket-dev] documentation reorganization
On Sat, Jul 2, 2011 at 9:41 AM, Ryan Culpepper r...@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 Culpepperr...@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
Re: [racket-dev] documentation reorganization
Four minutes ago, Robby Findler wrote: On Sat, Jul 2, 2011 at 9:41 AM, Ryan Culpepper r...@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. 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 Fri, Jul 1, 2011 at 9:41 PM, Ryan Culpepper r...@cs.utah.edu 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
On Sat, Jul 2, 2011 at 9:53 AM, Eli Barzilay e...@barzilay.org wrote: Four minutes ago, Robby Findler wrote: On Sat, Jul 2, 2011 at 9:41 AM, Ryan Culpepper r...@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. 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
Three minutes ago, Robby Findler wrote: On Sat, Jul 2, 2011 at 9:53 AM, Eli Barzilay e...@barzilay.org wrote: Four minutes ago, Robby Findler wrote: On Sat, Jul 2, 2011 at 9:41 AM, Ryan Culpepper r...@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. 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
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 e...@barzilay.org wrote: Three minutes ago, Robby Findler wrote: On Sat, Jul 2, 2011 at 9:53 AM, Eli Barzilay e...@barzilay.org wrote: Four minutes ago, Robby Findler wrote: On Sat, Jul 2, 2011 at 9:41 AM, Ryan Culpepper r...@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. 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 Fri, Jul 1, 2011 at 8:45 PM, 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: 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
