GitHub for English teachers | InfoWorld

In “GitHub for the Rest of Us”, I argued that GitHub’s superpowers can serve everyone, not just coders. Since then (2015), I feel like I overdid the deal. GitHub was, and remains, a deeply optimized tool for programmers creating and reviewing versioned source code. Other uses are possible but tricky, and the tools that I think could make GitHub more friendly for non-coders have mostly not arrived.

Recently, however, I reviewed what GitHub can do for non-coders. As I’ve helped colleagues write blog posts and documentation, I’ve been thinking about my editing process and finding tools that can help me tell the principles that guide it.

I have long imagined a tool that would allow a teacher to help students learn to write and edit. In “Thoughts in motion”, I explored what might be possible in Federated Wiki, an authoring tool that maintains version history for each paragraph. I thought it could be extended to allow for the kind of didactic editing I have in mind, but I haven’t found a way yet.

More recently, in “How to write a press release”, I tried to bend Google Docs for this purpose. To chronicle the process of editing a press release, I dropped a sample version 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 blog post reader could see each edit as a color-coded diff with an explanation.

The key enabler is GDoc File -> Version history -> Name current versionin the same way File -> See version historythe click navigation of the diff set. It’s easy to capture a sequence of editing steps this way.

But it is much more difficult to present these steps as I do in the post. It required me to create, name and organize a set of images, then link them to pieces of storytelling. It is tedious work. And if you want to build something like that for students, it’s a job you shouldn’t be doing. You just want to make the changes, tell them and share the result.

Why doesn’t the integrated change tracking in GDoc (or the equivalent in Word) meet the need? In these modes, changes and comments appear in document order. But the editing process doesn’t happen that way. When editing this sample press release, for example, I revised the title in Step 1 and explained my rationale there. Then in a later step, when editing the third paragraph, I saw that it required a title revision. So I made another change to the title and explained the rationale again. The layout I built for the blog post preserves that sequence, and I think it’s essential. Changes don’t necessarily happen in descending order of documents, nor should their narration. The narration must tell the story as it actually unfolds: moving around the document, revisiting the same passage several times for different reasons.

More recently, I tried a GitHub-based alternative to this GDoc technique. Again, the goal was not just to produce an edited version, but also to narrate the edits in a didactic way. I put the original document in a repository, made step-by-step changes in a branch, and created a pull request. We were then able to review the pull request, go through the changes, and review each as a color-coded diff with an explanation. No screenshots had to be made, named, organized, or related to the narration. I could focus all my attention on making and narrating the edits. Perfect!

Well, perfect for someone like me who uses GitHub every day. If not you, could this technique work? Let’s recreate my Google Docs example in GitHub and see how it goes. Imagine you’re not a coder, have never used GitHub, and don’t know (or want to know) about branches, commits, or pull requests. But you’d like to be able to create a presentation that walks a learner through a sequence of edits, with step-by-step narration and color-coded differences. At the end of this tutorial, you will know how to do it. I will describe the recipe carefully so that you can try it for yourself and decide if it is convenient. Or better yet, ask a friend who is an English teacher to experience it!

This screencast shows the end result of the technique I’m going to describe. You’ll see me click Next, in a review of a GitHub pull request, to walk through a sequence of commented changes.

If you want to replicate this and don’t have a GitHub account yet, create one now and log in.

Ready to go? Alright, let’s get started.

Step 1: Create a repository

Click it + button in the upper right corner, then click New repository.

github step by step 0a IDG

Here is the next screen. All you need to do here is name the repository, for example editing-step-by-stepthen click Create repository. I checked the Add a README file checkbox, and choose the Apache 2.0 license, but you can leave the defaults – checkbox unchecked, license None – because neither is important for our purpose here.

github step by step 01 IDG

Step 2: Create a new file

On your GitHub home page, click the Repositories tongue. Your new deposit appears first. Click on its link to open it, then click on the Add file scrolling menu.

github step by step 03a IDG

Step 3: Create a new branch, commit the change, and create a pull request

What happens on the next screen is confusing, but I’ll spare you the details because I guess you don’t want to know about branches, commits or pull requests, you just want to create the kind of overview I have promised box. So, just follow this recipe.

  • Name the file (eg. sample-press-release.txt
  • Copy/paste the text to revise into the edit box
  • Select Create a new branch for this commit and start a pull request
  • Name the branch (eg. edits)
  • Click on Propose new file
github step by step 03 IDG

On the next screen, name the pull request (for example edit the press release) and click Create pull request.

github step by step 04 IDG

Step 4: Visit the new branch and start editing

On the home page of your repository, use the main drop-down list to open the list of branches. There are now two: main and edits. Select edits.CEO

github step by step 06 IDG

On the next screen, confirm that you are on the changes branch.

github step by step 07 IDG

Click on the name of the document you created (for example sample-press-release.txt to open it.

github step by step 08 IDG

Click the pencil icon drop-down menu and select Edit this file.

github step by step 09 IDG

Make and preview your first edit. Here is my initial rewrite of the title. I wrote a title for the commit (Step 1: revise headline), and I added a detailed explanation in the box under the title. You can see the color coded diff above and the rationale for the change below.

github step by step 10 IDG

Click on Commit changesand you’re back in the editor, ready to make the next edit.

github step by step 11 IDG

Step 5: Access the pull request to review the change

On your repository homepage (e.g. https://github.com/judell/editing-step-by-step), click it Pull requests button. You will land here.

github step by step 12 IDG

Click on the name of the pull request (for example edit the press release) to open it. In the rightmost column, you will see links with alphanumeric labels.

github step by step 13 IDG

Click on the first of them to land here.

github step by step 14 IDG

This is the first commit, the one that added the original text. Click now Next to review the first change.

github step by step 15 IDG

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 browse through a series of commented changes.

Lather, Rinse, Repeat

To continue building the presentation, repeat step 4 (above) once per edit. I do this now.

…time flies…

OK done. Here is the final edited copy. To browse the changes, start here and use the Next button to advance step by step.

If it was a software project, you would merge edits branch in the main branch and close the pull request. But you don’t have to worry about all that. The edits branch, with its open pull request, is the end product, and the link to the first commit in the pull request is how you make it available to a learner who wants to revisit the presentation.

GitHub enables what I’ve shown here by wrapping the byzantine complexity of the underlying tool, Git, into a much more user-friendly interface. But what’s nice for a coder will probably still overwhelm an English teacher. I can absolutely imagine tools wrapped around the GitHub API that would simplify this technique for teachers and learners focused on the art of writing and editing.

In the meantime, however, it is possible to use GitHub to achieve a very good result. Is it practical? It’s not for me to say. I’m way beyond seeing this stuff through a beginner’s eyes. But if your English teacher friend wants to try, I’d love to know if he’s able to follow this recipe and if so, if he thinks it can help them help learners become better writers and editors .

Copyright © 2022 IDG Communications, Inc.