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 Impatient R