March 15, 2016 by Amanda Visconti

Peer review for my Programming Historian lesson on Jekyll+GitHub Pages website creation

I recently submitted a new digital humanities work for peer review: “Building a static website with Jekyll and GitHub Pages” at the Programming Historian. My lesson teaches you how to create and publish your own basic website or blog (which will look just like this and be publicly accessible on the Web, for free!) using some popular tech (the Jekyll static site generator, and GitHub Pages for web hosting). The lesson attempts to walk you slowly through the process and not assume any previous tech knowledge, and explains why you might be interested in creating a website this way instead of using other tools. (For what it’s worth, this blog you’re reading right now is run using the same tech as the lesson introduces—Jekyll and GitHub Pages!)

I invite anyone interested in trying my lesson to share your thoughts as you follow the lesson. Everything from ideas of things to add or highlighting parts of the lesson you liked, to “I got stuck here!”, “This sentence was confusing”, “I wish you’d explain why this step is necessary”, and “I understood this step, but I think someone with less of a tech background would be confused” is useful to me.

In exchange for providing feedback on my lesson as you work through the lesson, during the next month (through April 15, 2016) I will respond to any comments or questions from lesson users and I will personally try to make sure you can make it through the whole lesson all the way to your own basic public website. (Note: this lesson was originally Mac-only, but I just added and tested steps that should support Windows users as well. I haven’t coded on a PC in years, though, so I can’t guarantee that I’ll be able to troubleshoot all Windows-specific issues.)

Sharing comments on my lesson

Visit “Building a static website with Jekyll and GitHub Pages” to use the lesson.

Before starting the lesson, two alerts:

  1. You will need a Mac computer with a decent internet connection.
  2. One of the early steps of the lesson (“Xcode” in the “Installing dependencies” section) requires you to download a piece of Mac developer software that may take 3-5 hours to download. You’ll want to budget separate times (30-60 minutes, then 60-120 minutes?) to start the lesson, then come back after that download completes and do the rest of the lesson.

Ways of sharing your feedback:

  • Email: You can email me a list of your comments (maybe open the new email and add to it as you go through the lesson?)
  • Hypothesis annotation: Follow this special link to my lesson (it’s the lesson link, prefixed with to add your feedback right to the lesson! You’ll need to create a Hypothesis account if you don’t have one (or log in), then highlight any words or sentence you want to comment on and type in your annotation (more info on why using Hypothesis annotation is awesome back in this post).
  • GitHub: If you’re comfortable with GitHub, you can visit the peer review ticket for my lesson and leave your feedback as a comment on that issue.
  • Slack: Slack is a tool for online group chat; you can join over 400 digital humanists on the Digital Humanities Slack via this link. In addition to checking out all the “channels” (chatrooms dedicated to discussing specific topics, like annotation and DH teaching), we can use Slack to chat in real-time as you work through the lesson (e.g. send me a direct message). If this is interesting you but you’re not familiar with Slack, let me know and I’m happy to show you how to get started.

You can always privately contact my PH editor Fred Gibbs or me by email with questions about the lesson or the peer review process.

Type of feedback needed:

I’m seeking constructive comments—things that can help me make the lesson better and more accessible to users without a technical background. This includes places where you were confused, got stuck, quit, wanted more details, etc. I’m interested in both how I can make the lesson better for you specifically, and how you think I could improve the lesson for other users (especially those who may not have as much digital experience as you).

The Programming Historian has reviewer guidelines with more information about how to be a good, friendly reviewer and how their peer review process works.

What’s the Programming Historian?

Programming Historian is a collaborative web project offering “novice-friendly, peer-reviewed tutorials that help humanists learn a wide range of digital tools, techniques, and workflows to facilitate their research”. PH features “lessons” written by digital humanists; each lesson is a thorough, novice-friendly walk-through of not just how to use a specific digital humanities tool, but why you might want to. As such, they’re not classroom lesson plans (though they can be used as part of one!), but rather a pedagogical form of research writing where the new knowledge produced by the writer is all about making a methodology accessible to new users. (That’s how I’m explaining this work to my faculty review committee, by the way.)

If you’re interested in finding out more about digital ways of engaging with the humanities, check out the Programming Historian’s list of peer-reviewed lessons here (they aren’t just for historians, by the way). They’re all fantastic lessons, and run the range from more foundational concepts like preserving research data (by James Baker) or cleaning up digital text scanned from print books (by Laura Turner O’Hara), to methods of distant reading or a full set of lessons on learning the coding language Python.

I especially recommend Miriam Posner’s “Up and Running with” (if you’d like to create a website to show off a collection of digital or physical artifacts, like stuff from an archival collection or museum) or Matthew Lincoln’s “Using SPARQL to access Linked Open Data” (if you keep hearing about how collections like “the British Museum, Europeana, the Smithsonian American Art Museum, and the Yale Center forBritish Art” are publishing “APIs” or “linked open data” and want to know how this might be useful in your research/teaching).

You might also read more about PH’s peer review process in this “How did they make that?” article on the DH Commons journal.