2 min read

Writing Real-life Motivated R Guides

Saghir Bashir

Recently I posted1 a Getting Start in R guide which starts by explaining some key concepts in R and then demonstrates the tidyverse2 using a real-life dataset. Shortly after this, Dirk Eddelbuettel3 posted an equivalent “Tinyverse Edition4 using the data.table5 package. It was much more than I had expected as I thought that I was starting a one person project writing guides for a niche audience, and for my training courses and workshops. Below, I share my thoughts on my motivation for starting this project which I hope will motivate others to write similar guides.

My motivation was to produce accessible, “pretty” and high quality guides that showcases “real-life” R use cases.

  • Real-life

    • Use data that interests most or all of the target audience6.
    • Clearly explain the data and the context.
    • Clearly specify your objectives.
  • Accessible

    • Build a story around your data to tell the “technical” story at the same time.
    • For beginners start from zero and for others start one or two levels below what you intend.
    • Focus on the “how to do it” rather than the technical details.
    • Offer interpretations at each step (e.g. “the plot shows that … increases over time for … whilst it decreases for …”)
    • Write clearly and concisely.
    • Keep the document short.
  • Pretty

    • A printable and aesthetically pleasing document.
  • Quality

    • Peer review and user test guides (e.g. see the contributors to the “Getting Start in R” guide.)
    • Get feedback and contributions by sharing the source on sites like GitHub and GitLab.

For the aesthetics I decided to use the pinp7 package which produces a two-column PDF document (via LaTeX). I liked the way in which it presents the text, code and outputs which could be printed out (whilst minimising the number of pages) or read on an electronic device.

I am writing and intending to write more of these guides including “Case Studies in R”. The focus will remain on accessible, “pretty” and high quality guides as described above. You too could write your own guides. To get started clone and adapt the “Getting Started in R” GitHub respository. For future developments follow the @ilustat on twitter.