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, [EMAIL PROTECTED] 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? > >> >> > >> >>______________________________________________ > >> >>[EMAIL PROTECTED] mailing list > >> >>https://stat.ethz.ch/mailman/listinfo/r-devel > >> > > > > > ______________________________________________ > [EMAIL PROTECTED] mailing list > https://stat.ethz.ch/mailman/listinfo/r-devel > > -- Brian D. Ripley, [EMAIL PROTECTED] 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 ______________________________________________ [EMAIL PROTECTED] mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
