Good documentation has 2 purposes. The first is to help you think clearly about what you are doing. The second is to communicate your results to others. (If you can't communicate them to yourself, what hope do you have of communicating them to others?).

The left side of this diagrams embodies the "2 document" way of documenting work - an R script file that contains data and code and comments and a word processor file that contains all justification, description of methods, output, figures, and commentary. Material is copied between the two documents as needed. This system seems easier, as most people already know the word processor side of it, and most new R users are busy figuring out R.

The right side of the diagram shows the second way - everything is in one text file, which can be compiled to create output in various formats. During compilation, all the code is evaluated, and output and figures are generated and placed in the document.

This way of documenting work can seem very odd since you don't see the final product while you are working on the document. However, the payoff in simplicity (no copying and pasting, changes in the data automatically show up in the new document) is well worth it. In this set of videos, we'll show you how it is done, using the package rmarkdown, (integrated in RStudio). We’ll also demonstrate how to do this from the console.