Monthly Archives: January 2018

Good documentation

There is a great blog post entitled What nobody tells you about documentation which discusses what makes good documentation. Reading it made me realize why I like using R so much. Not only does it have great documentation but it follows many of the points listed in the above link. Every time I use the documentation in R I invariably learn something new or make some connection which had escaped me in the past.

R’s documentation

One of the primary reasons R is my favorite tool is its help system.  R’s help system is invoked by using the `?` command!  For e.g., if I want to learn about `lm` (linear model) I just type ?lm in the session and it will open up the help related to that function.  The most effective way of using R’s help system is to learn how to use it.  This is how I go about it:

  • Read the Description which is at the start of the page.  It generally lists the mnemonic that might help you remember the command.  For e.g., `lm` stands for linear model, `str` stands for *str*ucture of an R object.  Becoming aware of the mnemonic makes it easier to remember and recollect it later.
  • Briefly skim the Usage section.  See the various ways in which the function can be called and how it can be used.  Don’t worry about it too much if it doesn’t make too much sense at the moment.
  • Scroll all the way to the bottom of the help system which generally contains the Examples section.  Read the examples and literally type them in your R console to learn what the function does.  You can also use the `example` function to run all the code in the Examples section automatically.  Typing example(str) in your R console will run the examples for the `str` function.
  • Now scroll back up to the Usage section again and you will be able to make a lot more sense of what a particular function is doing.
  • Now slowly read the Details section to understand the details of this function.  This is the most thorough portion of the documentation! As you get proficient you will be able to grok this section easily and gain deeper insights about this function.
  • Now scroll to the Examples section and just above it is the See Also section.  This section lists all the functions/commands/options that are somehow related with the current function that you are learning about. Consistently exploring the recommendations made in the See Also section is the surest way to improve your proficiency in R.

The brilliance of R’s documentation system is that it aids in most of the different tasks mentioned in the link above.  The brief Usage section at the top of the documentation page and the Examples section at the end of the page give you a self-contained Tutorial and a How-to guide!  The Details section provides the Explanation about the function and all its input parameters whereas the Value section explains the output of the function. The See Also section shows how this topic is related with other similar topics which helps in learning how this function fits into the R environment.  All these various sections not only aid in your data exploration but helps you in getting a better understanding of the R environment and the tools it provides.