[Rd] barplot manpage (PR#7331)

[Dan Bolser]

Hey, 

Thanks very much for this information.

On Tue, 2 Nov 2004, Patrick Burns wrote:

>
>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.

oops!

>>>    
>>>
>>
>>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.

I can imagine its tough. I really like the perl model (sorry for brining
this up again) but there is a man page for each function, starting with an
overview (for quick reference) then simple description with some examples,
then a prolonged discussion.

There are several 'overviews' and tutorials in man page style with a
simple organization...

       Overview
           perl                Perl overview (this section)
           perlintro           Perl introduction for beginners

       Tutorials
           perlreftut          Perl references short introduction
           perldsc             Perl data structures intro
 
           perlrequick         Perl regular expressions quick start
 
           perlboot            Perl OO tutorial for beginners
           perlbot             Perl OO tricks and examples
           ...

And finally the package ships with the FAQ (which again has a man page
style serchable interface).


>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.

Yup, they should be as short as is necessary.


>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.

I see what you mean.


>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.

Sounds good.


>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.

:) I is tough I agree. The user should at least know where to start
looking.. Perhaps the R startup text could include a 'where to look' link?


>Patrick Burns

Thanks very much for your insight. Should I try to change docs, or should
I do something different?


>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")
>
>>
>>  
>>
>
>