Editing Slides for Class

For our training slides, we use Remark.js, an in-browser Markdown-driven slide show application that gives us the flexibility of HTML and CSS while retaining the PowerPoint “experience.” The code is hosted on Github and the slides are rendered on Github Pages.

Being believers in continuous delivery, we’re constantly making changes to materials, whether large or small changes to the content, either to improve the overall experience or adapt to the needs of a particular class. Remark.js makes this incredibly easy for us to do. Edits are easy (once you’re familiar with Markdown) and once a change is pushed, it appears online (almost) instantaneously.

To edit, you would first need to clone the repository to your local machine. Once you’ve cloned the repository, the process is similar to doing regular web design. Here’s the process we recommend:

1. Open the index.html file in your favorite text editor (we recommend Sublime Text).
2. Open a terminal window and navigate to the repository folder.
3. Start livereload on a port (or let it specify it on it’s own).
4. Open a browser and point it to localhost:<host number> where <host number> is the number either you or livereload is specified as serving the pages.
5. Edit the Markdown in a text editor and save your changes.
6. Watch as the changes automatically load.

In general, we ask content developers to commit often, tying the commits to Github issues for the class we’re building. This helps keep track of tasks and their resolution without going into individual commits and looking at all the code changes. The command git diff is very helpful when you inevitably forget what changes you made.

We also make heavy use of milestones to group issues together into sprints. This helps keep us focused on what needs to be done rather than getting bogged down in the extra things we’d like to do given the time.

We’ll be updating this post as we need to better describe the process of working with our materials. Feel free to leave your comments on our process with any recommendations you have for improving it.