I would like to suggest several I think straightforward modifications to the RStudio implementation of R help that I think would together render it considerably more helpful.
First, I think a person usually knows what kind of object they are looking for, and indeed, I think people are far more likely to look for function help than anything else. And I think if you are looking for anything else, you usually don't want a function. Finally, when looking for a function help, you typically want the help page for that function, and not just page that happens to mention it.
Actually, if there is more than one object with a specified name, it not only gives you those, but all sorts of other things -- names that contain that names, names that do not contain the name but that a spellchecker might return (e.g. if you have multiple packages that use the function "expand", you will get back help pages containing the words expansion, expended, and expenditure, none of them as the names of R objects.
Moreover, the page name and page description of the help page for a function may not even contain the name of that function. So you have a whole bunch of irrelevant pages and no guidance as to where the actual function is hiding.
So I think nearly everyone would be happier if the default behavior of help search was to return only functions that match the name you have supplied, if such exists, with two levels of expansion (via buttons, maybe). The first should return any kind of R object of that name (packages, data sets, parameters, vignettes, code demonstrations), and also page names that are not primarily pages for particular function, like the regex page. I think this level should also include help pages that mention the search term as a code object. Nearly all of these mentions can be identified mechanically by monospace formatting. And then a second level that gives the current behavior. The second expansion would be to the current search results.
I really think that virtually everyone would be happier with that, and especially newer R users who have to make more frequent reference to help pages.
There are also a number of straightforward additions that would be simple to implement and save typing and time. I urge you to add a button to run the code examples. When I was new to R I managed to overlook the existence of the examples function and thought you could only run them by cut and paste or in your head. I also learned that some of them contain invisible characters that make them behave incomprehensibly if run in this way.
Secondly, I think there should be a button to take you from the function help to the package help, i.e. the page you get to with help(package = "packagename"). This could have, and I think should have, been implemented as a hyperlink from the package name in parentheses at the top of each function page, but failing that, a button could have much same effect.
I came to R as a person with limited programming experience and an ambitious goal, and taught myself from books and help forums. I think people like myself, self-taught and aiming to program and indeed to metaprogram right out of the starting gate, represent a fairly small group within the R community, in part because, if my own experience is any guide, many of them will have given up before achieving a reasonable level of fluency. My early experiences of learning about R were rather reminiscent of William James’s description of learning in infancy: “… assailed by eyes, ears, nose, skin, and entrails at once, feels it all as one great blooming, buzzing confusion.” It is difficult to learn too many things all at the same time, and anything that makes it easier for learners to get a solid grasp on particular pieces can be a huge help in moving toward the central core of competencies that make it easier for learning to go forward.
But I also think that the "R for Data Science" route into R builds up a useful set of tools and basic programming skills much more easily than trying, as I did, to start with "An Introduction to R" and the R Core manuals. While this will, I think, ultimately make R accessible to a significantly larger number of students, I think you will also see a larger group attempting to teach themselves R without face-to-face teachers. I think we want these people to succeed. So it is not too soon to start asking how we can make life easier for this arriving cohort.
I think that R's goal to be the major gateway for statistical analysts into reproducible research, and perhaps more ambitiously, the front where statistical learning meets democracy, will ultimately call for a more fundamental reworking of R help, a best practices approach rooted in direct empirical measurement of learnability, such as:
-
** Intuitive:** Does the documentation convey a good intuitive understanding of what the function is for and how to use it?
-
Comprehensible: Can a relatively inexperienced R user understand how to use the function after reading it once or twice
-
Self-contained: Can most users glean what is necessary to actually use the function from the documentation, without needing to read a dozen other pages or have a more experienced person explain it to them.
-
Efficient communication: Does the help allow people who come to the page with some prior knowledge of the function and specific questions or problems to answer them quickly and easily?
But this is a task for another day.