From tplate at acm.org  Wed Nov  3 18:41:48 2004
From: tplate at acm.org (Tony Plate)
Date: Wed Nov  3 18:41:59 2004
Subject: [Rd] barplot manpage (PR#7331)
In-Reply-To: <4187DA6F.9020602@pburns.seanet.com>
References: <Pine.LNX.4.21.0411021602000.6111-100000@mail.mrc-dunn.cam.ac.uk>
	<4187DA6F.9020602@pburns.seanet.com>
Message-ID: <6.1.0.6.2.20041102124129.0bb1de70@mailhost.blackmesacapital.com>

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


[Rd] barplot manpage (PR#7331)
Tony Plate