Overview

For a while now, I’ve been meaning to write up a series of posts discussing my attempts at teaching a Git-based writing workflow in my technical writing courses. I’ll do my best here to document the choices, outcomes, and lessons from this process.

First, it’s worth considering the reasoning behind what might be a dubious decision. At the University of Washington (UW), we offer a series of courses on “Professional and Technical Writing.” While “professional” and “technical” might appear to be vague concepts at first, there is a long history of these courses being offered at universities, and they constitute a rich academic discipline within studies of composition and rhetoric. Here, “technical” more closely means specialized/expert knowledge that “technical writing” communicates, and “professional” writing is often synonymous with “business” writing, or writing one might do when writing on behalf of their employer.

My initial thought was that this sounds like a nightmare of a course to try to create a curriculum for–in a class with students working across all kinds of majors and disciplines, how can we train them for their diverse professional writing situations? What connects a student in finance to one in nursing? As for the technical writing side of things, if the goal of technical writing is the communication of specialized ideas in a discipline, what kind of instructor could possibly evaluate the various technical disciplines students might have? I haven’t been in a math class since I was in high school!

The course’s description is similarly open-ended: “Engages in professional genres and communication practices in light of emerging technologies. Students produce texts that prepare them to enter professional spaces.” What constitutes “emerging technologies”? In what discipline is it emerging? Are these writing technologies, or is it technology that students might encounter in their “professional spaces”? Again, what instructor has their finger on the pulse of every discipline’s technologies?!

As well, an initial difficulty was differentiating between what might be classified as the genre of “technical” writing and the profession of Technical Writer. My own (albeit limited) background with software development and open-source software meant that I was thinking of technical writing primarily in terms of documentation, either user-facing software documentation or documentation meant specifically for developers, maintainers, or contributors. Of course, there are other applications and documents produced by technical writers–handbooks, manuals, standard operating procedures, the list goes on. Yet, what is clear in the academic discipline of technical writing is that it does not necessarily attempt to emulate what a technical writer might do at their job so much as teach the ways in which to write about technical information in a more genre-based approach (that is, the “genre” of technical communication).

Reviewing syllabi from a variety of institutions, some basic themes emerged about how these courses were designed, as well as the basic assignment sequences that many taught. It seems like these courses consider a few basic documents to be pillars of the curriculum: memos/emails, reports, instructional manuals or technical descriptions, and a portfolio of job application materials. What I struggled with in this curriculum is the absence of “emerging technologies” in those assignments. Many of the assignment prompts I reviewed made the physical document the end goal of the project, but that implies a finality to technical writing that I think is not representative of what modern technical writing looks like (which is instead iterative and under constant development), and it is prioritizing a medium (paper) that is less and less relevant. Who reads an instructional manual when there’s a YouTube video about it? Who crafts a resume for print when we know it’s being filtered by an algorithm? If email is the best example of an “emerging technology,” that’s not a great sign for the relevance for the class! And, when are any of these materials (apart from an email) written in isolation and not collaboratively?

Another Way

In my attempt to develop an alternative way of teaching these classes, I was primarily concerned with both the use of technology and the kind of content being produced. I wanted my students to learn a possible way they could be asked to produce content while also attempting to teach content relevant to their soon-to-be professional lives.

Inspired by the work of the Write the Docs community, I wanted to teach technical writing in the “Docs as Code” workflow, that makes use of industry-standard tools for software development in the development of (often) software documentation. I would then attempt to adapt that workflow into the various writing contexts (and the varied content) that my students might find in their professional lives. That means both using and teaching Git to students, which was the first real site of pain in this process.

Anyone who has used Git to any degree is likely aware of its complexity, and it is likely safe to say that many experienced software developers only understand Git as much as they need to. Complexity is probably a polite word to describe the often confusing aspects of Git, but in the world of “Docs as Code” our use of Git is relatively limited compared to its full suite of abilities. First, though, a primer might be useful.

Git

Effectively, Git is a version control system that tracks changes made to files, and it allows for those changes to be tracked in a distributed way. The goal of this is so that development on software can work collaboratively, so that work on a piece of software can proceed non-linearly.

To consider a simple example of why this is useful, imagine a piece of software called Y version 1.0. Two developers work on Y version 1.0 and develop new features for it. They submit their separate features which both work fine for them, but when both features combine into a new version of Y, the software breaks. Since Git tracks all the changes made, it is trivial to revert to a version that was working, and allow those new features to be redeveloped. This might seem like something relatively minor that could be fixed with relative ease in less complex ways. But when you consider the scale and complexity of modern software, as well as how deeply distributed development of software is and how long its lifecycle is, the need for tools to track and have control over the history and versioning is crucial. As well, its creation of “history” by way of tracking every change made alleviates a lot of the need for remembering what was being done and why, or when something was developed or altered–Git will track all of this for you.

Given its ubiquitous status in the development of software, technical writers took up the use of the Git workflow in the crafting of documentation. Write the Docs has plenty of reasoning behind why they advocate for this workflow that are practical workplace considerations (e.g. feeling like you are working “with” developers instead of against them), but my interest in teaching it in my courses is more so that I think it is an interesting way to reimagine the labor involved in composition, and it moves writing from feeling “final” to feeling “iterative,” which is something I try to preach in all my writing classes.

As well, there is a partial admission being made here. While the humanities and the sciences rarely like to admit when the other has done something well, there is a lot to admire about modern software development if we zoom out a bit. Obviously, software projects exist on a scale that they never have before–as a simple example, the indispensable Linux kernel is now well past 30 million lines of code. As well, these projects are increasingly distributed, with no doubt thousands of developers working on some projects. Given that complexity, it is also true that products (roughly) continue to increase in quality and in features, and things still by and large “work” (again, in a very zoomed out sense, because of course all software still has unfound bugs). Given these elements–massive complexity, massive scale, massive distribution–and the way in which progress continues to advance, it would seem foolish not to study how software development manages this growth. While Git is not the sole reason, it is certainly a crucial part of managing these problems, so finding applications for it in writing contexts just seems to be finding ways to use what are provably effective technologies in the production of collaborative work.

Of course, the application of Git I will describe in my courses is a relatively small use of the power of Git, but I do think it allows students to get in the mindset of how Git functions, and to rethink the production of writing in a way that more closely emulates what they might do in professional writing contexts.

Briefly, the workflow

While future posts will describe the writing process with Git in more detail, the translation of Git from software development to writing is an important part of the theory of the course. If we consider the basic workflow of composition in a writing class, it might be this:

  • Author writes an initial draft
  • Draft is reviewed by peers and/or instructor(s)
  • Author revises draft based on feedback

In my experience, there is no real guarantee of that last step, but that’s basically how it goes. In an adapted “Docs as Code” workflow for my writing classes, it’s very similar:

  • Author commits “main” branch to repository
  • Contributors fork repository and make changes
  • Contributors push their branches back into “main” via merge/pull request
  • Author evaluates merge/pull request and suggests any changes
  • Author merges merge/pull request back into “main” and squashes conflicts

While these describe broadly similar processes of composition (authorship, peer review, revision), the ability of Git to manage the history of the document is where things deviate, and it’s what I’ll detail in future posts. As well, I’ll detail the changes to the curriculum I made over time, to move away from the traditional assignment sequence of technical writing and instead thinking about how the skills of technical writing could be taught in a way that might better emulate what a technical writer would do at their job.

As a final note, I consider myself an expert on none of this. I have used Git enough to get it functional and understand it in some theoretical way, but its features and its power far exceed the applications I have for it. That is a long way of saying that there is more that it can do than I could ever describe! Consider my use of it as an experiment with how to develop a writing class that uses it, not an absolute proof for its utility in writing classes. While I’m certainly an advocate for it, like everything, these ideas are always in a state of revision. Until later!