More R help files This page has the following sections: Vignettes Typical complaints A better order for help files Really better help files Vignettes If the function you are trying to learn comes from a package with a vignette, then reading the vignette might be a good thing to do before trying to tackle the help file. See More R packages. Typical complaints Help files tend not to be highly regarded. They start off at a disadvantage in that you wouldn't be reading one at all unless you had at least a minimal level of frustration. While there are many complaints about help files, the ones I've heard most often are: • No examples • Examples that depend on understanding other functions • Too terse of explanations A better order for help files I think the sections of R help files are in the wrong order. My preferred order is: • Description • Usage • Examples • See Also • Arguments • Value • Side Effects • other sections The key thing about this order is that examples are moved to near the top. This is better for the reader -- it is the point where most readers could benefit from examples. If the help file template were changed to this order, then it would be better for the writer as well. It would mean that thinking of examples would be the second thing the writer did, rather than the last. Really better help files While I'm in full agreement with complaints about poor examples, I think the typical complaint about terseness is off the mark. Even fewer people would read verbose help files than the currently "terse" help files. I suspect a better statement of the complaint is that there is important information missing. Or if the important information is there, it is not highlighted. In order to create a help system that is substantially better than the present one, I think the following elements would be necessary: • All the important information is present. • The user is neither overwhelmed nor distracted. • The system is simple enough for the developer to comply with it. I don't know how to achieve all those goals at the same time. Even getting two of them is a challenge. Back to top level of Some hints for the R beginner First Version: 2010 March 07   Last Modified: 2010 May 08 Direct access to this page is via http://www.burns-stat.com/pages/Tutor/more_R_readhelp.html