[R] two questions for R beginner

[Paul Hiemstra]

Brandon Zicha wrote:
> Hey Paul,
Hey Brandon, (adding R-help in the cc)

I agree with you that the documentation of R could be better, especially 
with more examples in code showing not only the common cases, but also 
more esoteric cases. It would be great if everyone invested a lot of 
time to write awesome documentation, but this is not the case. I just 
objected to the tone (I tought :)) I spotted. Some more comments are inline:
>
> Accepting the main point of my post - that the often VERY incomplete 
> help files appended to packages can be a major stumbling block for 
> getting up and running in R - I take your point.  I probably went a 
> bit to far with my language there.
>
> I would point out though that a great many parts of research (like 
> writing a bibliography - or searching for citations of any kind 
> usually) aren't much fun, but are an important part of research 
> related work.  Likewise, complete documentation (by which I hardly 
> mean a paper - looking at STATA help files as a minimum would be a 
> good start) is part of programming.  I agree that one needs to employ 
> some level of judgement, otherwise you will get helpfile that says 
> "First turn on the computer... then click the 'R' Icon...."  But, I 
> have myself created one or two STATA functions that I have put up for 
> public use - so I know how not fun, but necessary complete 
> documentation is.  Further, I didn't say that writing documentation 
> doesn't take time.  Everything takes time. My point was that relative 
> to actually creating the application - writing more complete 
> documentation takes very little time. If one invests the time to do 
> the 'fun' stuff of writing a new package for R, it seems reasonable 
> that taking the (proportionately) little time to write a nicer help 
> file would be the most 'professional' thing to do.  But, this could be 
> my illusion that all researchers seem themselves as professionals - 
> rather than an anarchic egoistic enclave of independent 
> self-interested paper producers.
This is what scientists get judged upon, not on how much software they 
publish and how good their documentation is. Furthermore, it is quite 
hard for a hardcore R programmer to judge what people find har about 
their software.
> I am notorious for assuming greater standards as an acceptable 'norm' 
> than my community at large :-)  Furthermore, you are absolutely right 
> that my standards are apparently even to high for many commercial 
> applications!  R help is sometimes downright good!
>
> So, if I accept that I am demanding S.O.B. and tone down my thoughts 
> of proper documentation and professionalism and adopt the (probably 
> more) reasonable perspective you do at the end of  "well, this is the 
> world we live in... and come on it's free" I totally agree that I 
> probably went too far!  But, better yet, I think that this observation 
> you make suggests a solution: Perhaps R could use a more integrated 
> and organized open source help system. I can think of a few 
> possibilities - the easiest being a wiki version of R help.  This way 
> users could add useful information to help files - such as more 
> examples, tricks, tips, and known problems.  This would take advantage 
> of the open source, free, user-community centered aspects of R, and 
> permit those with an interest in helping beginners to post notes for 
> beginners - on the help files.  I know that if such a wiki existed I 
> would have posted my recent example of constrain optimization I just 
> did recently.   It wouldn't be too difficult to add a function 
> wikihelp(X) that would open the wiki help page rather than the 
> standard help documentation.  Currently, help on any given command is 
> scattered all over help fora all about the web.  A central, indexed, 
> and easily referenced help system might be a solution.  Heck, such a 
> system could go a step further and link R-help listserv archives by 
> command thus centralizing and integrating the open-source user-built 
> information resource of the listserv into help().  How many e-mails to 
> this listserv begin with 'I just spent a few hours cruising the help 
> forums related to 'X' and couldn't find an answer.'
Sounds like a good addition, allowing people to add to the documentation 
as they see fit. There is ofcourse the R wiki, but this is not widely 
used and not firmly embedded into R itself. But how would we keep such a 
system you propose manageable, preventing it from becoming an enormous 
mess. Maybe some kind of moderation?
>
> I note that STATA has all their help files for the latest version of 
> stata available on the web (http://www.stata.com/help.cgi?contents).  
> How difficult would a similar system - only with R, editable and with 
> links to supplementary information - be to set up?  I can't imagine it 
> would be horribly expensive in terms of set up costs.
A problem is that there is no company that markets R that could set this 
up, the community is much looser, much more open source. Probably the R 
core team would be the closest thing we have.
>
> What do you think?
>
> Best,
>
> Brandon Z
>
>
> On Mar 2, 2010, at 1:16 PM, Paul Hiemstra wrote:
>
>> Brandon Zicha wrote:
>>>>>> What were your biggest misconceptions or
>>>>>> stumbling blocks to getting up and running
>>>>>> with R?
>>>
>>> Easy.  I terms of materials I have been unable to find good books 
>>> that introduce users to R from the perspective of someone familiar 
>>> only with packages like SPSS or STATA, or not familiar with 
>>> statistics packages at all.  Even introduction texts use jargon 
>>> without introducing it.
>>>
>>> I think that R-help files should be more thorough than they are, and 
>>> contain more examples.  I thought that STATA help files were 
>>> sparse!  The notion that 'R is a user community and thus they do 
>>> this in their spare time' is no excuse for those creating new tools 
>>> for R not developing complete help files.  It doesn't take that much 
>>> time relative to actually creating the new function.
>> Hi Brandon,
>>
>> I would disagree with your point that documentation doesn't take much 
>> time. Writing documentation that is suitable for both the advanced 
>> user (being a reference, and thus preferably short) and the beginning 
>> user (being sort of a tutorial, and thus prefererably longer) is 
>> quite a challenge, comparable to writing a good paper. Apart from the 
>> fact that it takes quite a while, it is also not much fun. Often 
>> people develop packages for their own research and put the software 
>> online so others can benefit, they don;t need the documentation 
>> themselves and don't get paid to write the documentation.
>>
>> So saying 'it's no excuse' really goes too far in my view. R is free, 
>> you did not pay several thousands of euros giving you the right for 
>> good support. Even the support is free through the mailing list. You 
>> can get a paid version of R at Revelution Computing. Then you can 
>> call them if there are problems. I'm not meaning to offend anybody, 
>> but I didn't agree with "is no excuse for those creating new tools 
>> for R not developing complete help files".  Partly the strength of R 
>> is in the open source, but sometimes, as with documentation, this can 
>> bite you. But I think the R docs aren't that bad, I've seen 
>> proprietary software that a worse job than R.
>>
>> my 2euro on the subject :),
>>
>> Cheers,
>> Paul
>>>
>>> In terms of actual R use - creating, using, and manipulating data 
>>> are the biggest frustration for those of the 'spreadsheet 
>>> generation'.  I get the impression that one needs to not merely 
>>> understand, but be fully fluent in the jargon of matrix mathematics 
>>> to even know what is going on half the time.  I find myself - even 
>>> now - using 'rules of thumb' that 'seemed to work' rather than fully 
>>> understanding what I am doing.  It is particularly discouraging when 
>>> many of those 'intro books' suggest using something besides R for 
>>> data manipulation - how clumsy is that!?
>>>
>>> I find the actual programming syntax itself is the easiest part to 
>>> master.  It is certainly more flexible - but without a particularly 
>>> sufficient increase in complexity - than trying to write script in 
>>> SPSS and STATA.
>>>
>>> Brandon Zicha
>>>
>>> ______________________________________________
>>> R-help at r-project.org mailing list
>>> https://stat.ethz.ch/mailman/listinfo/r-help
>>> PLEASE do read the posting guide 
>>> http://www.R-project.org/posting-guide.html
>>> and provide commented, minimal, self-contained, reproducible code.
>>
>>
>> -- 
>> Drs. Paul Hiemstra
>> Department of Physical Geography
>> Faculty of Geosciences
>> University of Utrecht
>> Heidelberglaan 2
>> P.O. Box 80.115
>> 3508 TC Utrecht
>> Phone:  +3130 274 3113 Mon-Tue
>> Phone:  +3130 253 5773 Wed-Fri
>> http://intamap.geo.uu.nl/~paul
>>
>


-- 
Drs. Paul Hiemstra
Department of Physical Geography
Faculty of Geosciences
University of Utrecht
Heidelberglaan 2
P.O. Box 80.115
3508 TC Utrecht
Phone:  +3130 274 3113 Mon-Tue
Phone:  +3130 253 5773 Wed-Fri
http://intamap.geo.uu.nl/~paul