Peer Review

Occasionally when I am reading about coding practices, I am struck by the richness and clarity which maintains what is essentially a writing process. I think there is something more to be examined there, and, perhaps once the boat book is done and the narrative project is underway, there will be time to consider how software writing is writing and what that may mean for how we think about writing.

All of this is occasioned, by the way, by a [post on StackExchange][se], about how to deal with code review in, what other programmers argue, is an unstructured review process. In the case, of the original question, a team member has his code reviewed by the assistant lead for the team, who makes changes without talking about the changes with the writer. The writer naturally wants to own his own code and to understand what he did wrong, but he also feels like the assistant lead occasionally makes corrections before a piece of code is completed — and so there may be “working errors” in the code (what writer he can’t commiserate over a terrible sentence, or paragraph even, that’s there as a placeholder?) — and occasionally adds code that the writer doesn’t feel is very readable. (This is all incredibly rich stuff for thinking about composition and writing in general, no?)

As I note above, other programmers basically respond that the individual involved, the assistant lead, is not so much the problem as the code review system itself. It’s worth thinking about the fact that the only time we offer writing experiences as structured as this in the university environment is in courses, and usually only in courses focused on writing. Sometimes, depending on the faculty member, we may offer such an experience to students working on theses and dissertations.

Why don’t we offer more? Because our infrastructure is so poor. Using a word processor with the commenting and reviewing features turned on is a first step, but it hardly allows the writer, and the reviewer, to compare versions of a document, to track changes across multiple iterations. Jonathan Goodwin and I took our first steps in this regard this past fall when we decided to compose our essay using *LaTeX* and used a *Git* repository hosted on [*Bitbucket*][bb]. (The repository is currently private, but we do plan to make it public.) *Wouldn’t it be exciting if every student began their university career with a repository that they maintained and with which various instructors and peers interacted, contributed, or reviewed over the course of their education?*

Towards that end, there were a couple of suggestions for *peer review* platforms made in the StackExchange thread that I thought I would note here. The first package mentioned is [Atlassian’s *Crucible*][ac], which I mention here first as well because it should work well with *BitBucket*, which is also by Atlassian. (And if you haven’t signed up for BitBucket, you should. It’s free for academics. The chief advantage over *GitHub* is, as noted above, the option to have private repositories.) More importantly, just attend to the way the elaborations possible in the review process offered by something like *Crucible*:

* Crucible provides configurable options to track and complete reviews (defined workflow, moderator, one or more participants).
* *Reviews are about comments.* Crucible supports fully threaded comments so teams can discuss code at different times and locations.
* Reviewers can navigate several revisions of a file under review. If a newer revision of a file is available, Crucible will indicate that the file is outdated, and provide a shortcut to quickly add the latest revision.
* Quickly create pre-commit reviews while you’re in the flow of coding from the command lineā€“no logging into Crucible, no context switching.
* Some source (or any text) just needs to be discussed without a formal review process. Crucible provides ways to discuss code informally.
* To help stay on top of your reviews, you can: subscribe via email or RSS to review activity, including new comments, status change, or file additions; bookmark reviews or review comments as favorites to revisit them later.
* Sometimes developers forget about code reviews that need their attention. Automatically or manually notify reviewers who have not completed your code reviews. Set up reminders for reviews with due dates or manually “nudge” them to get their attention.
* All of this can be managed, and reviewed, through a dashboard.

That is a fantastic set of options, and, again, much of it is available either at a significant discount for academic institutions or for free for open source, non-profits, and classrooms. (See the [Pricing] page for details.)

Crucible is not the only game in town, and there are straight-up open source alternatives. One is [Review Board][rb]. Like Crucible it offers a dashboard that summarizes what an individual user (writer!) usually wants to know. It also hosts a diff viewer that allows you to see at a glance if things have simply been moved — a nice feature to have in any diff viewer.

Okay, there is a lot of terminology above that is going to be foreign to most humanists, and even a lot of scientists. E.g., repository (repo), commit(s), diff (short for difference). And the overviews for each of these packages, Crucible and Review Board, reveals that everything is in this weirdly unformatted form known as plain text, an equally strange term (and concept, unfortunately) for most non-coders.

My underlying argument is all this could, and should, change. I recognize that the kind of writing we do as scholars, and scientists, is different than the kind of writing done by software developers, but that shouldn’t stop us from adapting useful technologies when they present themselves. The argument for this is pretty straightforward: the computer was not invented as a writing tool, and yet almost everyone I know uses it as such. (And, in fact, we complain when our students don’t use it as a writing tool but as a distraction device.)

This is, obviously, a tentative first step in a much longer, I hope, argument. I can’t give it the attention I would like right now because I am in the middle of writing myself. While my next research project is focused on the intersections of narrative and ideology, I would like to take some time out to think about how “writing is writing.” For now, I am tagging this as such, *writingiswriting*. We’ll see what accrues to this tag over time.


Leave a Reply