Introduction to Version Control

Today we start a new series titled Housekeeping: How to Keep Your Publications Shop Tidy. Some years ago we saw plenty of books about decluttering: your closets, your basement, your kitchen, your bedrooms, your garage, your recreation room or family room, your attic. The idea was that we were all swamped with detritus from every stage of life, and if you don't free yourself now, you'll go under and never appear in public again. If your house ain't tidy, these authors suggested, what can you say about the rest of your life?

STC chapter president Nancy Allison spoke recently on the topic Disaster Recovery: Fixing a Documentation Mess. Her introduction begins: "Do you ever feel like you’ve just been handed a giant mess? The documentation is in complete disarray and needs to be tidied up, or perhaps beaten into submission." Nancy adds in her bio that she "has a particular fondness for wading into a documentation catastrophe and restoring order." If you have worked in the field of technical publications for even a short time, you know what she's talking about.

At the end of RTFM: Acronym Whose Time Never Came, I mention five housekeeping practices that help you keep things squared away and under control. That's the army ideal: beds made in the morning, dishes clean after every meal, uniform crisp, shoes polished, floors mopped and lockers in order. Engineering types and other technical people may not care for the army life, but if disorderliness and a sprawling sense of incipient chaos cause you daily frustration and anxiety, you naturally start to think about how to shape things up.

I'd like to start with version control. It's a big subject, but we can move a few steps from the starting line. We might inquire, at the outset, what should I consider if I'm about to select a version control system for my shop? That focuses attention on processes related to version control. Many writers may have to live with what they already have in place, but the hypothetical case of how you might improve your versioning if you could lead to helpful improvements.

Moreover, changing to a new system may not be as hard as you think. Tools have improved over ten years and more. Besides, the question is only a point of departure. I don't want to advocate that you change your version control system. The one you have may serve your needs well. "What should I consider?" questions help us think about what we might want from any version control system we may try - and what we want to avoid.

I've introduced the phrase version control system without pausing to define it. One of the worst experiences for any writer is to find suddenly that you don't know which version of a document is your latest. Or you encounter another member of this unpleasant family of problems: you can't find the latest version; your versions have branched, so you have two or more latest versions; team members tried to reconcile two versions, and you can't tell where they left off; you overwrite changes in the latest version by accident, or someone accidentally overwrites your latest changes. Everyone has dealt with at least one of these situations, and you hope you never need to do it again.

A long time ago, project managers and software specialists designed version control systems to prevent these time-consuming, painful, and demoralizing detours. Software development teams are often large: without a version control system, team members cannot collaborate. The same goes for teams that produce technical publications. Because requirements for software builds and technical publications seemed to parallel each other, technical writers often dropped their files into the same folder structure the developers used. That meant they used the same version control system, too.

I don't need to explain all the reasons that arrangement did not work so well. It took a little time, but people began to recognize that everyone - developers, writers, quality assurance, managers, and engineering support - would do better if the pubs team managed their files separately from the software files. Consequently software repositories and doc libraries would live under their own versioning regimes.

I want to note five features of a document versioning system to prepare for the next article in the series: 1) automatic file backup, 2) file locking or something equivalent, 3) convenient file sharing and distribution, 4) revision history, and 5) effective integration with authoring and publication tools. If a document versioning system does not incorporate these capabilities, it probably won't meet the needs of a team larger than two.

The next article takes a look at these capabilities, to illustrate how they work no matter what tools or methods you use. We may have a chance to use SharePoint as a sample environment. I mention this collaboration toolset not because I think they it's the best, but because most doc managers and authors know about it. SharePoint is in wide use because it integrates with Microsoft Office. Typically document versioning comes built into content management systems, which can run into some money.

A number of shops, small or getting bigger, do not use formal versioning systems. Others use old but adaptable systems that, come what may, have served reasonably well for as long as anyone can remember. Some shops tolerate legacy systems that may not integrate with other applications or document control systems that support cloud computing. We'll try to take a number of situations and needs into account as we investigate how various versioning systems contribute to efficient document management.