Earlier today I saw the hundred bazillionth question about how to use the paste function. My initial response was “take a look at example(paste) to see how it works”.

Then I looked at example(paste), and it turns out that it’s not very good at all. There isn’t even an example of how to use the collapse argument. Considering that paste is one of the first functions that beginners come across, as well as being a little bit tricky (getting to understand the difference between the sep and collapse arguments takes a bit of thinking about when you are new), this seems like a big oversight.

I’ve submitted this as a bug, with a suggested improvement to the examples. Fingers crossed that R-core will accept the update, or something like it.

It got me thinking though, how many other base functions could do with better examples? I had a quick look at some common functions that beginners seems to get confused with, and the following all have fairly bad example sections:
In base: browser, get, seq
In stats: formula, lm, runif, t.test
In graphics: plot
In utils: download.file, read.table

If you have half an hour spare, have a go at writing a better example page for one of these functions, or any other function in the base distribution, then submit it to the bug tracker. (If you aren’t sure that your examples are good enough, or you need advice, try posting what you have on r-devel before submitting a bug report. Dealing with bug reports takes up valuable R-core time, so you need to be sure of quality first.)

This seems like a really easy way to make R more accessible for beginners.