Patrick Burns' and Brian Ripley's general comments about the difficulty of writing good documentation are on the mark, but the specific case of the man page for "barplot" does seem amenable to at least some slight improvements, e.g.:

(1) Change "expansion factor" to "character scaling factor" or "character magnification" in the descriptions of 'cex.axis' and 'cex.names'

(The documentation for 'barplot' uses 'expansion factor', while the documentation for 'par' itself uses two other different terms 'magnification' and 'scaling' to describe various 'cex' related arguments. Both common sense (my own, at least) and guidelines I could find on the net suggest that it is better to consistently use a single term to refer to a single concept.)

(2) add "par" to the "see also" section

I looked in the "Writing R Extensions" manual, but could find no guidelines for the style of documentation. I also looked on the web, and I was surprised at the difficultly of finding any guidelines for software user documentation or software requirements specification (the documentation for R function is like a combination of the two, as far as I can make out.)
Can anyone point to some guidelines that people who wish to improve R documentation might find useful?


-- Tony Plate

______________________________________________
[EMAIL PROTECTED] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel

Reply via email to