On 02/01/2009 7:33 PM, Stavros Macrakis wrote:
On Fri, Jan 2, 2009 at 5:56 PM, Duncan Murdoch <murd...@stats.uwo.ca> wrote:
I don't agree. If you add too much technical detail to a topic, then people
don't "work through it". I'd say the r<dist> pages generally give enough
detail now, but not too much. If you add every detail that might interest
someone somewhere, then they'd all be hard to read.
Duncan, Daniel,
Thanks for your responses.
I agree that it's a delicate balance between too little and too much
information on individual documentation pages -- especially when, as
in this case, a number of different functions (r<dist>) share some
content (RNG). That said, I find in general that R documentation
pages are somewhat on the "too little" side. In particular, I'd find
it useful if there were more references to synthetic overviews: a link
from the connection page to an overview of I/O; a link from the runif
page to an overview of distributions; etc.
One structural problem we have is that it is hard to make a useful link
between different types of documentation. You can cite one of the
manuals from a man page, but it's hard to make a convenient link to a
particular section. Vignettes are similar: when they exist, they often
give exactly the overview you're looking for, but it's almost by chance
that you find them.
I spent a little bit of time putting things in place so that
help.search() could look through vignettes and manuals, but got
sidetracked before it was complete, so I doubt it will make it into 2.9.0.
Duncan Murdoch
______________________________________________
R-help@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-help
PLEASE do read the posting guide http://www.R-project.org/posting-guide.html
and provide commented, minimal, self-contained, reproducible code.
