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.
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 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 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
On the next screen, title the pull request (e.g. edit the press release) and click Create pull request.
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
Here’s the next screen.
Click the name of the document you created (e.g. sample-press-release.txt to open it.
Click the pencil icon’s dropdown, and select Edit this file.
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.
Click Commit changes, and you’re back in the editor ready to make the next change.
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.
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.
Click the first one of those to land here.
This is the first commit, the one that added the original text. Now click Next to review the first change.
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.
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/
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.
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!
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?
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/
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.
Look into the tool repobee. I stumbled across it this morning and it’s usecase may fit your need. The downside is it is a terminal tool..
I would opt for fossil, instead of git(hub) or git(lab)
For me, fossil is much richer and has that beautiful “UI”
we can open in a browser in our localhost…
– Reference
– https://fossil-scm.org/home/doc/tip/www/quickstart.wiki
– https://notxor.nueva-actitud.org/2022/06/26/fossil-scm.html
Thanks for the tip, Cypher. What’s the equivalent in fossil to the workflow I’ve shown in GitHub? The key thing is the ability to hand somebody a link that steps through a sequence of narrated edits and shows the narration and the diff together?
Jon,
Wouldn’t MS Word work for this (and be far more familiar)? Granted, folks would have to come to understand the Reviewing capabilities/interface. There’s friction here as you say, but I have to think this would be easier (if I’m understanding your intention).
Here’s a very small sample I put together…
Load this demo Word file: https://1drv.ms/w/s!Aiig7FS_c0gPgotVHVodtN0H-5pPMw?e=KnkoYA
Click the edit button.
Click Ok to track changes enabled. (Should be in reviewing mode.)
Click “Review” menu item to toggle review menu visible.
Navigate changes via the “Track Changes” menu or click the comments (linked to changes).
Yes, I think Word can meet the need, as can GDoc. In both cases, I’d be wanting an API-based wrapper around these tools to sequence the edits, and enable the student to step through the sequence by clicking a Next button. And I’d like to be able to deliver that experience by handing the student a link that jumps straight into the sequence.
The demo I made in GDoc and then GitHub has a nice example of why I think sequence matters so much. I revised the headline in the first step. But then a few steps later I revised it again, in response to something that happened in step 3 or 4. That’s how editing works: you move around in the document, and may revise the same sentence or paragraph more than once. The Word/GDoc interface presents changes in document order, but I want to present them in the order I make the edits, which often entails circling back to an earlier place in the document, or jumping forward.
GitHub despite its high barrier to entry just happens to be a way to preserve that order. But yes, absolutely, let’s find ways to make Word and GDoc do that too! Or maybe they already do, and I’m just now aware of how?
Yea, Word’s change tracking _is_ top down. I agree, sequence matters. (I overlooked that in your post, which is odd since I’m such a Ted Nelson fan.) Back to your question… I think your process is good and easy _enough_ that a motivated teacher could use it, but I’m no teacher (despite my best efforts). I think I often see such ideas from the confines of my ivory tower, and good ideas to me don’t always resonate with the “average” user. However, it’s best to air them out. Sometimes one’s good ideas take hold – given enough time. You continue to contribute to that pool. Thanks.
Thank you!