Re: [Rd] barplot manpage (PR#7331)

From: Tony Plate <tplate_at_acm.org>
Date: Thu 04 Nov 2004 - 04:41:48 EST

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?


R-devel@stat.math.ethz.ch mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel Received on Thu Nov 04 05:20:51 2004

This archive was generated by hypermail 2.1.8 : Fri 18 Mar 2005 - 09:01:05 EST