runif limited precision
On 02/01/2009 7:33 PM, Stavros Macrakis wrote:
On Fri, Jan 2, 2009 at 5:56 PM, Duncan Murdoch <murdoch at 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