Adventures in GitHub

This semester I am trying something new for teaching

A while ago Brian Croxall suggested that what we need in higher educaiton is a Git Hub for syllabi. Or more precisely Brian was suggesting that we ought to alter the frame by which we think about creating, modifying, and sharing syllabi. In his piece for Profhacker Brian suggests that we should think of syllabi as itterative documents, which we borrow, and share with each other. The model for this is GitHub, the platform for sharing coding projects. When coders want to build on the code of other coders they do what is called “forking,” basically taking the code from the original creator, and building on it for one’s own purpose (with a link to the original source). I am not going to recast the enitre frame here (although I think Brian’s argument is useful, a way to think about our practice of producing syllabi), instead I want to share how I am going to attempt to do this.

I wanted to start producing syllabi in such a way that it was easy for others to see, to borrow, to reference, to iterate, borrow from others and publish in a range of formats (web, print, etc.). The idea here is to write and store the syllabus in such a way that makes it easy to use/reuse, push to various locations, and to “rip-mix-burn” with what others are doing. Rather than go into all the details about why I would want to do this (again see Brian’s post and the links he provides as a starting point) I want to walk thru how I am doing it. This is very much still a work in progress, so I have a lot yet to figure out.

The Format: Writing in Separate Markdown Files

I started by writing in Markdown. There are lots of reasons I am chosing to write in markdown rather than say a Micorsoft Word document, another word processor, or even in html. The most important of which though is its portability. It is relatively easy (more on this later) to write in Markdown format and then export it to one of the other formats I need (to say the web, or a word processing document). Also markdown has the advantage of having really simple syntax (just a few things to remember) and yet handling everything I need, bold, italics, headers, blockquotes, lists, and links. In fact I have started writing everything in markdown first, including this blog post and my current research articles. It had a really short learning curve, and after just a few days it feels totally natural. I like to write in a program that on the left is the writing format, and on the right is a live formated rendering of what I am typing. This really helped with learning to write in Markdown. I mostly write in a program called Retext but there are lot of options for writing in Markdown depending on what system you are using, and I suspect in the future I will just compose in a basic text editor (but for now the live preview is a nice crutch).

For now I keep the schedule of readings in in one file, the course description (policies, textbooks, grading policy etc.), the course information (time, date, classroom, office hours) all in separate files. I actually think that in the future I might separate out the description into a few more files (making it easier for someone to just borrow or “fork” that part of the syllabus). I think the more discrete units that I break the syllabus into the easier it will be to source, modify and credit it. You can see all the files I currently have here. There are other things in that folder (.odt files and .pdfs I’ll get to those in a moment). So essentially to edit the syllabus I just edit the markdown files (the ones listed as .md).

The Core: GitHub

I am organizing this all through GitHub, or rather publicly sharing it all through GitHub. I actually write and edit the files on my computer and then “push” the changes to GitHub which is updated. This allows others to view, share, and modify portions or all of my syllabus rather easily. More importantly GitHub handles the tracking of this sharing and referencing (forking). So if someone wants to “fork” my syllabus all they have to do is joing GitHub, set up their own account and fork the syllabus. For those unfamiliar with Github you might want to check out The New Yorker Article. Simply put though GitHub is a place for sharing information, iterating that information, and tracking those iterations, whether they are yours or someone elses. Really the ideal platform for sharing syllabi and assignments. And since the files are published in markdown you can actually just read the text right there, no downloading and opening a file.

One of the key features of a Git system is that it acts as version control, this way I can easily keep track of the changes I am making to the syllabus. Or, for that matter others can see the changes I have made to the syllabus over time.

As the semester progresses I am going to add in an assignments folder where I plan to write up all the assignments as separate files. This will help me to iterate the assignments, to borrow my assignments from others, and to share them with anyone else.

Publishing the Syllabus

So I’ve started to think across all areas of my writing about separating the text from the particular venue. Just writing in close to plain text (hence the turn to markdown) then exporting the text to whatever format I want, applying the “styling” at the point of publishing not the point of composition. Right now I am using Pandoc to compile all the markdown files, and convert them to various formats (.odt, .docx, .html). In fact the .odt and .pdfs in the link above were produced this way. The “syllabi template” file just applies the styling so that when the markdown files are compiled into a document file it looks like a print syllabus. Doing it this way made it ridiculously easily to put my syllabus online as html but to also produce a print copy to hand out on the first day.

The key is that I will only edit the markdown files and have the others be updated. Right now I have to manually update (i.e. tell Pandoc to do this) but in the future I want to get this step automated, so that I edit the markdown file and the website will automatically update, along with the “print” version.

This Wasn’t Easy

The problem with this is that it wasn’t easy. There was a lot of learning curve both with GitHub and converting files. I could justify this as both related to my field of study and I am interested in figuring this out (not the least of which because I am thinking about using this as a way to share research as well). But honestly this isn’t really a workable solution for most academics, especially the non tech savvy. Even with programs that make interacting with GitHub easy, or file conversion easy, this is still a bit labor intensive. I think now it actually saves me time as I can write the syllabus once and update it across venues easily. But I certainly haven’t reached the point where I am saving myself more time than it took to learn. But I do think both in terms of composition and in terms of sharing this is certainly a model for how we as academics can share our pedagogical resources.

Which Brings Me To . . .

I think what we need is a way to do this (outside of the CMS’s Universities use), but do it with relative ease. Something like GitHub for syllabi. Enter Coursefork. This seems to be the niche they are going for, easy to use uploading of teaching materials, with the ability to edit, share, and credit others work. I’m not associated with Coursefork, although I have been able to use the Alpha system and they seem to be headed in the right direction. I don’t know if they will succeed or not, but I will say that I hope that something like this does succeed, both in the practical sense (a platform like this would be useful) and a more abstract sense (the idea of forking and sharing syllabi). After spending sometime working like this I am convinced that forking and sharing syllabi is the way to go, we just need practical tools for it, along with the conceptual framework of “forking.”

Note: I want to give a lot of credit to Andy who not only already did this (so I modeled my workflow after his) but also had put his EMAC 2321 syllabus on GitHub which serves as the reference for the COM 200 syllabus I put up. Unfortunately in the learning I didn’t get the forking right and so my syllabus doesn’t show as a “fork” of his, something I need to figure out how to correct here.