[Rd] barplot manpage (PR#7331)

[Patrick Burns]

Dan Bolser wrote:

>On Tue, 2 Nov 2004, Tony Plate wrote:
>
>  
>
>>Yup, I think you're right.  R is a volunteer project, so what needs to 
>>happen to improve the documentation is that some capable volunteers (or 
>>just one volunteer) step forward.   It is the prerogative of the members of 
>>R-core to decide whether to spend their time on improving documentation or 
>>improving the functionality (or merely having a life).
>>

I thought we had agreed that members of R-core are not allowed lives.

>>    
>>
>
>I could try making better pages for the functions I use.
>
>
>  
>
>>However it is worth noting that R does have really quite good documentation 
>>for a piece of software of its kind, compared to both other open source and 
>>commercial software.
>>    
>>
>
>That is very true. However, I still maintain that the emphasis is on
>developers and not learners.
>

[ ...]

As someone who has spent an inordinate amount of time writing and
revising help files, I can assure you that writing help files is about as
difficult of genre as exists.  There are numerous constraints which, taken
together,  yield  no  feasible  solution.

As you rightly maintain,  the  help file  should be  written  for people who
may not even know what the purpose of the function is, and for people
who are not native speakers of the language -- rather than just a mnemonic
for the author of the code.  On the other hand help files need to be short
because no one reads documentation, and no one squared reads long
documentation.

Things get even worse for graphics functions -- partly because they are so
complex, and partly because we subconsciously think they should be easy
because we are well tuned to interpreting the graphics themselves.

At heart it seems to me that you are asking for a new form of help file --
taking them from 2 dimensions to 3. For example, the "axis.lty" item in the
barplot help file would look similar "on the surface" to what it 
currently is
(though perhaps phrased better).  But there would be the ability to 
drill into
the item to learn about axes, line types and possibly other things.

To implement this vague idea, all that needs to be done is for someone to
come up with a workable system, and people to fill in the text.

The big problem that I see with documentation, which you also allude to, is
that the (confused and frustrated) user needs to seek out the appropriate
documentation when trouble happens.  Said confused and frustrated user
would rather the documentation came along by itself to say what went wrong.
I'm much more at a loss for this.

Patrick Burns

Burns Statistics
patrick at burns-stat.com
+44 (0)20 8525 0696
http://www.burns-stat.com
(home of S Poetry and "A Guide for the Unwilling S User")

>
>  
>