[Rd] barplot manpage (PR#7331)

[Dan Bolser]

On Tue, 2 Nov 2004, Prof Brian Ripley wrote:

>There are books about R: have you tried reading a couple (or more)?

Not from cover to cover. 

I turn to use a function, I find a problem using that function, I look at
the online information for that function and I can't understand it ...
somthing is wrong.


>And what training have you had in technical communication (which includes 
>honing your reading skills)?

You should put that in a document called 'What you should know before
using R'...

I am a bad reader - sorry to admit that.


>In contrast, I find the Perl documentation very hard to use and
>insufficiently precise, and would be surprised if many learners used it
>before reading one of the Perl books.

Apples and oranges... Actually much of the perl books are dumped from the
online documentation system.


>Precision is a great virtue in written technical communication. Far more 
>common a problem on R-help is a far too vague statement of the problem, or 
>a user failing to read the documentation.

Why do so many people appear not to have read the docs? Just lazy people I
guess... Why not advertise courses in technical communication from the R
site?

I am sorry for going over the top. Your comments are quite reasonable,
however, I just think they are a little unreasonable. The vast majority of
the people just want to get going. They want to read about science, not
technical documents. They want to quickly test their ideas with
visualizations they can drop into papers and presentations (without
spending half a day on trying to work out how to format the graph or
manipulate the data).

R is very very very nice, I wouldn't be using it (and I certainly wouldn't
be 'wasting my time' complaining about it) if it wasn't. I just wish it
were easier learn how to use while actually using it.

>On Tue, 2 Nov 2004, 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 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.
>> 
>> 
>> >What would need to be improved in the document "An Introduction to R", 
>> >specifically, the subsubsection on "Graphical Elements" (under "Graphics 
>> >Parameters List" in "Graphical Procedures", p 77 in my copy) in order that 
>> >it would meet the criterion of being "less formal man pages"?  There's a 
>> 
>> Having it to hand when you need it (i.e. at the command line) like other
>> man style documentation systems. Also having reference to all the related
>> functions. 
>> 
>> My problem is this, my barplot has decided to use SI for big numbers. I
>> would rather it use the number in full... How do I do it? I don't know...
>> Some of my column labels are going missing... how do I fix it... I don't
>> know... My legend is in the top right when the top left would be much
>> better, how do I fix it... 
>> 
>> I read ?barplot, but I didn't *see* what I needed - I don't doubt that
>> someone who already knew how to do these things could look at ?barplot and
>> say that its fine. I can't say that.
>> 
>> 
>> 
>> >lot to be said for having the "less formal" documentation being organized 
>> >around concepts rather than specific functions (as the man pages are), 
>> >because the conceptual organization allows more organized discussion of how 
>> >functions work together and which are the appropriate functions to 
>> >accomplish certain types of tasks.
>> 
>> True, but that is a different task. A 'guide to use' is different from a
>> 'user guide'. I find time and time again tiny problems (conceptually
>> trivial) which are very frustrating in R, I don't want to ask a question
>> on the list, I don't want to trawl the archives for the answer, I want a
>> clearer explanation of how the darn function works!
>> 
>> I think having a concept based approach is essential (as you say), but the
>> 'nuggets' should be posted around to the different functions, so each
>> concept for each function is indexed under that function for easy
>> retrieval (if that makes sense).
>> 
>> 
>> >Maybe inserting automatically generated "see also" references to "An 
>> >Introduction to R" into the man pages would help beginners (and those who 
>> 
>> I think so. 
>> 
>> >have to deal with cleaning up bug reports that aren't really bugs)?
>> 
>> Sorry, I made some comment about 'constantly wanted to improve the info
>> pages' on the mailing list, (with regards to a Wiki dump of the said pages
>> into the user domain). One reply said that instead I should request that
>> the documents be changed via a bug report from the R web site. 
>> 
>> I honestly want to give my time and energy to help users like me use R. I
>> very often find the man pages totally cryptic and often frustrating.
>> 
>> Sometimes the examples read like entries from a Perl obfustication
>> competition - people taking delight in doing things as tersely as possible
>> to 'get kudos' from their 'knowledgeable' peers. 
>> 
>> The Perl documentation system is a joy to use. However, we shouldn't
>> compare apples and oranges...
>> 
>> Thanks for your help, and sorry for the inconvenience. I am (still) only
>> trying to help :)
>> 
>> All the best
>> Dan.
>> 
>> >-- Tony Plate
>> >
>> >At Tuesday 12:52 AM 11/2/2004, Dan Bolser wrote:
>> >
>> >>Should these be in the (see also section)?
>> >>
>> >>Like I said, the pages read fine if you understand the content already. I
>> >>think some less formal man pages would drastically reduce the traffic on
>> >>the R mailing list.
>> >>
>> >>Just a hunch,
>> >>Dan.
>> >>
>> >>On Mon, 1 Nov 2004, Tony Plate wrote:
>> >>
>> >> >Look at the help page for "par" for explanations of "cex" and "lty".
>> >> >
>> >> >The use of 'mp' is as a variable, as in
>> >> >
>> >> > > mp <- barplot(....)
>> >> >
>> >> >The next paragraph refers to this variable.
>> >> >
>> >> >-- Tony Plate
>> >> >
>> >> >At Monday 05:12 PM 11/1/2004, dan at bolser.co.uk wrote:
>> >> >>Full_Name: Dan B
>> >> >>Version: R 2.0.0 (2004-10-04).
>> >> >>OS: Fedora 2
>> >> >>Submission from: (NULL) (80.6.127.185)
>> >> >>
>> >> >>
>> >> >>The man page for barplot (?barplot) is confusing...
>> >> >>
>> >> >><quote>
>> >> >>cex.axis: expansion factor for numeric axis labels.
>> >> >>cex.names: expansion factor for axis names (bar labels).
>> >> >></quote>
>> >> >>
>> >> >>What is an 'expansion factor', and what does it do in this context?
>> >> >>
>> >> >>
>> >> >><quote>
>> >> >>axis.lty: the graphics parameter 'lty' applied to the axis and tick
>> >> >>           marks of the categorical (default horizontal) axis.  Note
>> >> >>           that by default the axis is suppressed.
>> >> >></quote>
>> >> >>
>> >> >>This makes no sense unless you know what it does already (which I 
>> >> don't). So
>> >> >>this is more of a programmers cleft note in a 'common language' than a
>> >> >>function
>> >> >>documentation page.
>> >> >>
>> >> >><quote>
>> >> >>say 'mp', giving the coordinates of _all_ the bar midpoints drawn,
>> >> >></quote>
>> >> >>
>> >> >>Say what?
>> >> >>
>> >> >>______________________________________________
>> >> >>R-devel at stat.math.ethz.ch mailing list
>> >> >>https://stat.ethz.ch/mailman/listinfo/r-devel
>> >> >
>> >
>> 
>> ______________________________________________
>> R-devel at stat.math.ethz.ch mailing list
>> https://stat.ethz.ch/mailman/listinfo/r-devel
>> 
>> 
>
>