From ripley at stats.ox.ac.uk  Tue Nov  2 18:39:40 2004
From: ripley at stats.ox.ac.uk (Prof Brian Ripley)
Date: Tue Nov  2 18:43:43 2004
Subject: [Rd] barplot manpage (PR#7331)
In-Reply-To: <Pine.LNX.4.21.0411021602000.6111-100000@mail.mrc-dunn.cam.ac.uk>
Message-ID: <Pine.LNX.4.44.0411021725420.31139-100000@gannet.stats>

There are books about R: have you tried reading a couple (or more)?
And what training have you had in technical communication (which includes 
honing your reading skills)?

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.

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.

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@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@stat.math.ethz.ch mailing list
> >> >>https://stat.ethz.ch/mailman/listinfo/r-devel
> >> >
> >
> 
> ______________________________________________
> R-devel@stat.math.ethz.ch mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
> 
> 

-- 
Brian D. Ripley,                  ripley@stats.ox.ac.uk
Professor of Applied Statistics,  http://www.stats.ox.ac.uk/~ripley/
University of Oxford,             Tel:  +44 1865 272861 (self)
1 South Parks Road,                     +44 1865 272866 (PA)
Oxford OX1 3TG, UK                Fax:  +44 1865 272595


[Rd] barplot manpage (PR#7331)
Prof Brian Ripley