Chapter 1 Overview

1.1 Open online educational resources (OERs)

OERs are educational resources that are public and freely available to students (or anyone) through the web. There are already numerous OER databases linking to numerous free textbooks across many domains of study (e.g., see the BC library OER site). These texts are often disseminated under a creative commons license, which allows anyone to mix, match, edit, update, and transform those texts, and then share them again with the public at large under the same license. Finding existing OERs can be a good starting point for developing your own content.

1.2 What is this tutorial?

This tutorial shows how a few open-source tools can be brought together for quicky developing and sharing content in the form of online books and webpages. The tools require some downloading of free programs (all cross-platform), but once in place, allow you to write and format text with minimal syntax, and then easily compile your source documents into multiple formats, including web-books, .pdf’s, and e-pubs.

Basic steps

Figure 1.1: Basic steps

This tutorial also covers tools to enhance student interaction with the content, including the ability for students to select text in a web-book and then post comments about the text. Depending on the pedagogical goals of the instructor, posts could be to critically evaluate portions of the textbook, supplement sections with additional examples, and tag sections in need of revision or that were particularly helpful. All of these comments can be made publically accessible so that everyone viewing the textbook can see all of the comments as they are posted (inline, corresponding to the sections that were annotated). Furthermore, the database of annotations can easily be extracted and used for revising the text, or other purposes.

1.3 Can I see an example of what you are talking about?

Yes, there are many working examples already. As the preface mentions, this tutorial is an example. So the bells and whistles you see here constitute one example of an end product. Some additional examples include a Research Methods for Psychologist’s textbook, and a Programming for Psychology textbook that I made using the tools in this tutorial.

If you want to see examples of the inline commenting features, simply follow the directions in the preface of the above two books. Inline commenting is made possible by the hypothes.is browser add-on tool. It is simple to install, requiring that you sign up with hypothesis, and then follow their directions to install an add-on for chrome, or a bookmarklet for other browsers. When you turn on hypothesis viewing these web-books, you will be able to see any public comments made by other people.

1.4 The toolbox (what do I need to download)

Each of the chapters in this tutorial will discuss each of these tools in more depth, along with links to many helpful tool-specific resources already available online.

1.4.1 R

R is a free and open-source programming language primarily developed for statistical analysis. R has a large community of active open-source developers who are makin R better and more powerful everyday. R comes with existing packages for statistical analysis, but can be extended to accomplish many more tasks by downloading and installing additional packages. Download and install before you download and install R-studio.

1.4.2 R-studio

R-Studio is a free and open-source GUI for R. For those of you familiar with the Matlab environment, R-studio looks similar.

1.4.3 Markdown and R Markdown

Markdown is a simple mark-up language for creating .html files viewable in web-browsers. HTML (hyper-text markup language) is a powerful, but visually cluttered syntax for creating content to be displayed in web-pages. Markdown allows you to easily write text while avoiding writing html syntax. For example, This document is written in markdown.

RMarkdown is R’s version of markdown. It’s basically the same as markdown, but allows you to inject and run R code inside a markdown document. This is especially useful when you are writing documents that contain output from data-analysis you have conducted in R. This document is an .Rmd file (Rmarkdown). The paragraphs are plain text, and the header’s (level I, II, III) are defined by #’s.

1.4.4 Bookdown

Bookdown is an R package for compiling Rmarkdown documents into various formats, including web-books, .pdf’s, and epubs. This incredible package, along with the knitr package, does much of the heavy lifting, allowing writer’s to focus on content generation, rather than the technical details of deploying that content to the various formats. Once the .Rmd files are written, deployment can is a single-click. Bookdown also provides different formats for styling the output, and styling is customizable.

1.4.5 Github

Github is a version control software development tool/website. Github provides a free option for hosting static web-pages (e.g., you could deploy your web-book to github), and allows you to store the source code for generating your book in an online repository. This allows others to easily copy your source code and make suggested edits that you can incorporate back into your content. This web-book is hosted using github pages, and the source code for this book is hosted in a github repository. Downloading the github repository will give you all the files you need to compile this book, and by editing the text in this book, you can change it into your own.

1.4.6 Hypothes.is

Hypothes.is is a web-browser add-on for annotating the web via inline commenting. This allows anyone to select a snippet of text in a web-browser and then post a comment about the selected text. Annotations can be made publicly or privately. All public annotations can be viewed by anyone else running hypothesis on the same website. Using Hypothesis with your web-book allows you to engage students in interacting with the textbook by allowing them to contribute to content generation (by posting new content), or content revision (by tagging sections in need of revision).

1.4.7 hypothesisr

hypothesisr is an r package for scraping annotation data collected through the hypothesis app. This could be used for identifying tagged sections in need of revision, or for other analytic purposes.

1.4.8 Zotero

Zotero is a free and open source citation management tool. It is cloud-based with both browser and app versions. It is easy to create .pdf libraries along with citation information, and then compile bibliographies with citation keys for quickly citing articles. The R bookdown package is compatible with latex-style bibliography files that can be exported by Zotero.

1.5 Quickstart

If you want to skip to getting up and running, follow these steps. If they all work, then you should be able to copy the source code this book, compile it and display it as a webbook (or pdf or epub), and then start modifying the text content to create your own resources.

1.5.1 Download all the programs, and set-up needed accounts

  1. Download and install R
  2. Download and install R-Studio
  3. Open R-studio, choose the packages tab, search for the package “bookdown”, download and install
  4. Create an account with Github
  5. Download and install Github Desktop

1.5.2 Create a Github repository

  1. Create a new repository on the Github website, give it a name
  2. Clone the repository to your local computer using Github Desktop
  3. Open the local repository

1.5.3 Copy and compile this repository

  1. Download this repository as a .zip file to your computer
  2. Copy the contents of the folder to your new local folder for your github repository
  3. In Github Desktop you should now see that there are many new changes to your repository. Commit the changes (uploads them to the online repository)
  4. Open the OERbookdown.Rproj in Rstudio, this is an R project file that will automatically point R to the files in this folder.
  5. In Rstudio, on the top right panel, choose the Build tab, then click build book.
  6. If everything goes smoothly, you will have compiled this book into a web-book, a .pdf and an epub. The compiled books are in the “docs” folder
  7. After the compilation process, a viewable web-book should be displayed on your computer.
  8. Upload any changes in your repository to Github using the commit button in Github Desktop.

1.5.4 Serve your book on the web using github pages

In addition to providing free repositories, Github also allows files in the repositories to be served as web-pages. Set this up using the following steps:

  1. Log-in to your github account through a web browser
  2. Click on your repository
  3. You should see all of your files from your local computer in the online repository
  4. The html files to build the web-book are located in the docs folder. Github allows html files in a docs file to be rendered as a webpage
  5. Go to the settings page for your repository. 21.Scroll down to the Github Pages options
  6. Turn on the option to use github pages with the docs folder
  7. Github should now display a url where you can view the web-book.

1.5.5 Make your own book

Now that you have the workflow established, you can create your own book by editing the text content of the .Rmd files in this repository. Change the text, then build the book again, then upload it to Github, and you should have a new web-book.

1.6 Description of Files in this Repository

  • OERbookdown.Rproj An R-studio project file that automatically points R-studio to all of the files in this folder.

  • _bookdown.yml set a few options, like folder where book is compiled, currently “docs”

  • _output.yml more configuration options

Each .Rmd file is an Rmarkdown file containing the text for each chapter. The index.Rmd file contains some initilazation settings, and the preface content. All other .Rmd files contain the text for each chapter. These need to be edited to create new chapters. Add as many new chapters as you want by creating a new .Rmd file with an incremented number for the new chapter.

  • index.Rmd Contains initialization settings, and preface content
  • 01-Overview.Rmd Chapter 1 content
  • 02-R.Rmd Chapter 2 content etc.
  • 03-Bookdown.Rmd
  • 04-Github.Rmd
  • 05-Hypothesis.Rmd
  • 06-Zotero.Rmd
  • 07-references.Rmd

Other files

  • book.bib bibliography file
  • DESCRIPTION miscellaneous
  • docs : this is a folder containing the compiled book in html, .pdf and epub formats
  • Figures : a folder to store figures that are imported into the book
  • LICENSE a license file
  • packages.bib bibliography file
  • preamble.tex supporting tex file for rendering
  • README.md the README file displayed on Github
  • style.css style file for webbook
  • toc.css style file for webbook table of contents

hypothesisR