https://blog.jonudell.net/2022/08/27/github-for-english-teachers/ Skip to content Jon Udell Strategies for Internet citizens Menu * index GitHub for English teachers 27 Aug 202227 Aug 2022 ~ Jon Udell I've long imagined a tool that would enable a teacher to help students learn how to write and edit. In Thoughts in motion I explored what might be possible in Federated Wiki, a writing tool that keeps version history for each paragraph. I thought it could be extended to enable the kind of didactic editing I have in mind, but never found a way forward. In How to write a press release I tried bending Google Docs to this purpose. To narrate the process of editing a press release, I dropped a sample release into a GDoc and captured a series of edits as named versions. Then I captured the versions as screenshots and combined them with narration, so the reader of the blog post can see each edit as a color-coded diff with an explanation. The key enabler is GDoc's File -> Version history -> Name current version, along with File -> See version history's click-driven navigation of the set of diffs. It's easy to capture a sequence of editing steps that way. But it's much harder to present those steps as I do in the post. That required me to make, name, and organize a set of images, then link them to chunks of narration. It's tedious work. And if you want to build something like this for students, that's work you shouldn't be doing. You just want to do the edits, narrate them, and share the result. This week I tried a different approach when editing a document written by a colleague. Again the goal was not only to produce an edited version, but also to narrate the edits in a didactic way. In this case I tried bending GitHub to my purpose. I put the original doc in a repository, made step-by-step edits in a branch, and created a pull request. We were then able to review the pull request, step through the changes, and review each as a color-coded diff with an explanation. No screenshots had to be made, named, organized, or linked to the narration. I could focus all my attention on doing and narrating the edits. Perfect! Well, perfect for someone like me who uses GitHub every day. If that's not you, could this technique possibly work? In GitHub for the rest of us I argued that GitHub's superpowers could serve everyone, not just programmers. In retrospect I felt that I'd overstated the case. GitHub was, and remains, a tool that's deeply optimized for programmers who create and review versioned source code. Other uses are possible, but awkward. As an experiment, though, let's explore how awkward it would be to recreate my Google Docs example in GitHub. I will assume that you aren't a programmer, have never used GitHub, and don't know (or want to know) anything about branches or commits or pull requests. But you would like to be able to create a presentation that walks a learner though a sequence of edits, with step-by-step narration and color-coded diffs. At the end of this tutorial you'll know how to do that. The method isn't as straightforward as I wish it were. But I'll describe it carefully, so you can try it for yourself and decide whether it's practical. Here's the final result of the technique I'll describe. If you want to replicate that, and don't already have a GitHub account, create one now and log in. Ready to go? OK, let's get started. Step 1: Create a repository Click the + button in the top right corner, then click New repository . [step-by-st][step-by-st] Here's the next screen. All you must do here is name the repository, e.g. editing-step-by-step, then click Create repository. I've ticked the Add a README file box, and chosen the Apache 2.0 license, but you could leave the defaults -- box unchecked, license None -- as neither matters for our purpose here. [step-by-st][step-by-st] Step 2: Create a new file On your GitHub home page, click the Repositories tab. Your new repo shows up first. Click its link to open it, then click the Add file dropdown and choose Create new file. Here's where you land. [step-by-st][step-by-st] Step 3: Add the original text, create a new branch, commit the change, and create a pull request What happens on the next screen is bewildering, but I will spare you the details because I'm assuming you don't want to know about branches or commits or pull requests, you just want to build the kind of presentation I've promised you can. So, just follow this recipe. * Name the file (e.g. sample-press-release.txt * Copy/paste the text of the document into the edit box * Select Create a new branch for this commit and start a pull request * Name the branch (e.g. edits) * Click Propose new file [step-by-st][step-by-st] On the next screen, title the pull request (e.g. edit the press release) and click Create pull request. [step-by-st][step-by-st] Step 4: Visit the new branch and begin editing On the home page of your repo, use the main dropdown to open the list of branches. There are now two: main and edits. Select edits [step-by-st][step-by-st] Here's the next screen. [step-by-st][step-by-st] Click the name of the document you created (e.g. sample-press-release.txt to open it. [step-by-st][step-by-st] Click the pencil icon's dropdown, and select Edit this file. [step-by-st][step-by-st] Make and preview your first edit. Here, that's my initial rewrite of the headline. I've written a title for the commit (Step 1: revise headline), and I've added a detailed explanation in the box below the title. You can see the color-coded diff above, and the rationale for the change below. [step-by-st][step-by-st] Click Commit changes, and you're back in the editor ready to make the next change. [step-by-st][step-by-st] Step 5: Visit the pull request to review the change On your repo's home page (e.g. https://github.com/judell/ editing-step-by-step), click the Pull requests button. You'll land here. [step-by-st][step-by-st] Click the name of the pull request (e.g. edit the press release) to open it. In the rightmost column you'll see links with alphanumeric labels. [step-by-st][step-by-st] Click the first one of those to land here. [step-by-st][step-by-st] This is the first commit, the one that added the original text. Now click Next to review the first change. [step-by-st][step-by-st] This, finally, is the effect we want to create: a granular edit, with an explanation and a color-coded diff, encapsulated in a link that you can give to a learner who can then click Next to step through a series of narrated edits. Lather, rinse, repeat To continue building the presentation, repeat Step 4 (above) once per edit. I'm doing that now. ... time passes ... OK, done. Here's the final edited copy. To step through the edits, start here and use the Next button to advance step-by-step. If this were a software project you'd merge the edits branch into the main branch and close the pull request. But you don't need to worry about any of that. The edits branch, with its open pull request, is the final product, and the link to the first commit in the pull request is how you make it available to a learner who wants to review the presentation. GitHub enables what I've shown here by wrapping the byzantine complexity of the underlying tool, Git, in a much friendlier interface. But what's friendly to a programmer is still pretty overwhelming for an English teacher. I still envision another layer of packaging that would make this technique simpler for teachers and learners focused on the craft of writing and editing. Meanwhile, though, it's possible to use GitHub to achieve a compelling result. Is it practical? That's not for me to say, I'm way past being able to see this stuff through the eyes of a beginner. But if that's you, and you're motivated to give this a try, I would love to know whether you're able to follow this recipe, and if so whether you think it could help you to help learners become better writers and editors. Share this: * Email * Twitter * Facebook * Reddit * Like this: Like Loading... Posted in . [8a2baae][8a2baae] Published by Jon Udell View all posts by Jon Udell Post navigation < PreviousHow to rewrite a press release: a step-by-step guide 6 thoughts on "GitHub for English teachers" 1. [65bed32][65bed32] cynthiakiser says: 27 Aug 2022 at 3:46 pm Have you looked at Authorea? I wonder if its version system has the features you are trying to create: https:// support.authorea.com/en-us/article/ how-to-track-changes-made-by-co-authors-12mdge5/ Loading... Reply 1. [8a2baae][8a2baae] Jon Udell says: 27 Aug 2022 at 11:00 pm I'm aware of it, but not that aspect of it, good point. "It has been described as "Google Docs for Scientists" -- nice! Come to think of it, I reckon a GDoc script could improve on the primitive solution I came up with there. And likewise a tool built on the GitHub API could improve that primitive solution. Loading... Reply 2. [ebbc951][ebbc951] Peter Yates says: 28 Aug 2022 at 6:44 am I'd recommend using Markdown instead of plain text. It's basically the same except it gives you some really basic formatting (headings, bold, italics, links, lists). It's automatically rendered in GitHub and you can enable 'rich diffs', which show small changes side-by-side - I think they'll be easier to read than regular diffs (they look closer to Google Docs). Just change your extension from .txt to .md to get started! Loading... Reply 1. [8a2baae][8a2baae] Jon Udell says: 28 Aug 2022 at 11:40 am Yes, absolutely. For this example, given the inherent complexity of GitHub, I went with the Simplest Thing That Could Possibly Work. In general Markdown would be better. I haven't checked: does the rich diff happen in the pull-request-review scenario? Loading... Reply 3. [ec11d5d][ec11d5d] Justin says: 28 Aug 2022 at 8:41 am Hi John - have you ever looked at Almanac? They're a bit more business centric but have the branching and versioning features you mention. https://helpcenter.almanac.io/handbook/almanac-help-center-4JVsMe /version-control-basics-Hd5KRwzG4TDnj9HyoAh8d4EPm2MmORwJ https://almanac.io/ Loading... Reply 1. [8a2baae][8a2baae] Jon Udell says: 28 Aug 2022 at 11:44 am Looks nice! For the particular purpose I have in mind, branching and versioning are necessary but not sufficient, the goal is to enable a teacher to build a presentation that steps a student through a narrated sequence of edits. The GitHub scenario just happens to meet that need -- awkwardly to be sure, but I can confirm it works if you're willing/able to engage with GitHub in that way. It's far from an ideal solution, and I hope better ones will emerge. Loading... Reply Leave a Reply Cancel reply Search for: [ ] [Search] * All Posts * Hypothesis annotations * Bio Follow Blog via Email Enter your email address to follow this blog and receive notifications of new posts by email. Email Address [ ] Follow Feed RSS feed RSS - Posts Creative Commons LicenseCreative Commons License Strategies for Internet Citizens by Jon Udell is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License. * index Powered by WordPress.com. %d bloggers like this: