I was fairly slow to adopt Git (having been raised on other version control tools), but, needless to say and like most of us, it’s now a daily component of my work flow. And certainly using Git myself is a much different beast than using Git in a massive organization with hundreds of engineers all working from the same code base. Which is to say: there’s still plenty of room for my Git skills to grow.
Recently, though, I’ve come to appreciate another value of Git, which hadn’t previously crossed my mind or been written about elsewhere (such that I’ve seen):
Git is a valuable tool for technical writers.
One interpretation of that sentence is that you can use Git to manage revisions to a document. Sure. That’s completely logical and not surprising. But I’ve found something more nuanced in my Git usage as a technical writer.
Frequently, and especially in books, an example script or site will be built up over the course of a chapter or several chapters. This approach is a great way to solidify and build upon existing skills, quickly convey new ideas, and to walk the reader through a natural-like development flow.
This common approach has two implicit problems, however. First, if the reader doesn’t go through the material sequentially, or carefully, they may be confused when they encounter a later version of the code that doesn’t match that which they’re building off of in the current step. Second, if in version 3 of the script, you realize you need to add an HTML tag to version 1, it’s easy to miss also making that change for versions 2 and 4, leaving you with an inconsistency in the material. (This is where most of my printing errors have arisen.)
Git can solve both of these problems.
By mapping evolutions of code to Git commits, you’ll have an obvious record of what changes you made when. Thus, when you go to explain the next sequence of changes (e.g., in the book), you only have to look at the relevant commit (or, more appropriately, series of commits). Further, you can, if need be, rewrite the commit history and squash your commits to make it look like certain changes were put in place earlier or in a more organized manner.
Taking this a step further, if you put your code into GitHub (or any public repository), with the commit history, your readers can then use the diffs to track the changes you made, and the changes they’re supposed to make, in order to see what the full code should look like at specific stages. At the end of Chapter 1, the code would look like so; in Chapter 5, these edits were made; and so on.
It’s a total win. The only caveat to this approach (that I’ve discovered thus far) is that the commits themselves can end up being ham-fisted: less focused and atomic than commits would ordinarily be for strictly programming purposes.
So this may not be all that revolutionary of an idea, but it’s one I’m going to keep playing with for a while. It all recently came to light for me when working on the two example chapters of “The Yii Book“. When I write an entire sample chapter, my approach is to develop all the code first, and then write out the chapter itself, explaining the steps I took to get to the final product. Because I wanted to put the two Yii examples into GitHub anyway (at some point), it made sense to use Git from the onset. Although my commits were too big and ungraceful, they demonstrate the steps I took to convert a standard Yii application site shell to a CMS/blog or an e-commerce store. Then, when I went to write the chapters–I just finished Chapter 22 and am about to start writing Chapter 23, I just walked through my commit history to explain the steps I took. Thanks to Git and GitHub, I can see every change I made in every script for each task. I didn’t have to worry about missing something, and when readers read the book and look at the code, they can easily get quick “before and after” snapshots of the application.
