Avoiding Version Control Hairballs

Version control is one of the biggest headaches I face as a technical communicator. Oddly enough, the technologies that have made document sharing so easy and storage space so plentiful have also opened up new and recurring nightmares for anyone working with electronic documents. An engineer I knew at NASA used to call paperwork problems “hairballs,” akin to those nasty things cats cough up until they’re gone. For me, version control is one big, nasty hairball.

The problem occurs when you’ve got more than one draft of a document due to edits, updates, or changes. Sometimes you don’t create the extra draft(s), another person does. Which document counts as the “master” or “live” copy?

It gets even more fun when you’ve got a document that runs a couple hundred pages and you’ve got a couple dozen people commenting on it. How do you get past this and make your life less painful? Below are s0me lessons learned the hard way, one learned as recently as last month.

If possible, assign only one person to be the document owner

If you’re lucky, you’ll get to lay down the law and get yourself assigned as the only person assigned to own/touch/edit the official copy of the document. That way, anyone else sending in a document can only make their own copy and send the edits to you for incorporation. Good luck with that: it’s become less and less common in my experience.

Use Track Changes

Microsoft Word has this lovely feature under the Review tab called Track Changes, which highlights for a writer/editor whatever changes a previous user has made to a document. Track Changes is your friend, though in the spirit of full disclosure, it can cause documents to crash if there are too many changes being tracked. It’s also good to accept changes on occasion to prevent your really big, important document from getting “crashy.”

Trusting an editor to magically see all of the changes you’ve made is a recipe for disaster. Still, if you’ve got (or are) a contributor who has a mental block about Track Changes, you can always try the Merge or Combine Documents function, which will, as the name suggests, combine the contents of one document with another, with only the differences between the two showing up as tracked changes. It’s ugly and can raise questions about which changes  came from whom, but it can be done.

I get into discussions occasionally with people who inform me that Microsoft Word “sucks” and that there are better programs out there we should be using. On that matter, I will politely disagree. Plus, however much the anti-Microsoft crowd might prefer Mac‘s Pages app (which truly is inferior for half a dozen reasons), Word is the most common shared document format out there, so you might as well live it, love it, learn it. It’s been the ocean in which I’ve swam for 20+ years.

Include a date in the file name

You can ensure that people know which is the latest document simply by including the date of the version in the file name. If more than one person accessed the doc that day, you might have to add a time stamp (I use the 24-hour standard) as well.

Set rules for using file sharing services

Online file sharing services such as DropBox, Google Drive, or ownCloud have made it possible for multiple people to access a shared document and even edit simultaneously. Some folks would prefer that only one file and one file name be used to prevent file sprawl. However, multiple users accessing the files make new versions more likely than ever. And these services are not foolproof (if you want to hear some colorful profanity, ask a NASA person sometime about the agency-internal “Windchill” application).

Here are my issues with these services as I’ve experienced them in the workplace:

  • Some services, such as Dropbox, allow multiple to access the same document at the same time by downloading a copy instead of checking it out like a library book. Users can see what the “latest” version is by reading the update day/time in the system. However, problems crop up when more than one person uploads their edited version of the document at the same time. The first person to upload “wins,” with the document of the second person going into limbo (see Remember where you’re working, below).
  • Another problem comes up if someone makes a bunch of changes and saves over the original master doc but those changes are rejected. However, it is entirely possible that their changes caused other content or changes to be deleted/lost (see Save your work! below).
  • Google Drive’s writing app (Google Docs) allows multiple people to work in the same document at the same time. My biggest gripe with Google Docs is simply that it lacks the functionality of MS Word, especially when it comes to page formatting. I’m also not happy with multiple people working on the same text at the same time. Much like the problem above, suppose you spend a good deal of time working on a few paragraphs only to have one of your parallel editors delete that whole section because they don’t think it belongs there. Who wins that argument? How does the software decide?

I realize that some of my reactions here are a factor of my age, my relationships with technology, or my attitude toward collaborative writing and editing. I use these file-sharing tools because they make some things more convenient. However, I’m still convinced that a document is likely to come out looking and reading better if you have only a single person doing the writing/editing.

Save your work!

This was the issue I ran into last month. Say you’ve got multiple people working on a file that’s too large to email (usually >20MB) and you’re at a remote location where a high-speed T1 line isn’t available. In that case, you’re left with the expedient of passing the file around on a USB or other external media. Here’s what can happen if you’re not paying attention:

  • Person A makes changes to the document and saves it to the USB drive. The USB drive is then handed over to Person B.
  • Person B downloads the document to his hard drive and makes changes. Before handing off the USB drive, however, Person B makes more changes and then saves them to the USB drive.
  • Person C now has the document. She might make changes to the USB version or not. Perhaps she saves the document to her hard drive, makes changes there, but neglects to update the USB drive.
  • The USB drive is now handed off back to Person A for final approval, only to find that some changes discussed by the group are on the drive while some aren’t. To try and resolve the changes, Person A, B, and C then discover that they all have slightly different versions on their computer, none of which match what was supposed to be on the USB drive.

In this case it’s not just a matter of saving your work but saving it in all of the places where you NEED it to be. Saving a copy of a shared document on your hard drive is fine, but if it needs to be handed off, just make sure that you have saved the latest version in both locations.

Remember where you’re working

Opening and editing a document from email also can be vexing if you neglect to take the file out of the temp files where computers save email attachments. As soon as you close the document, poof! It’s gotten lost in the Temp File Forest of Fangorn. Good luck finding it again. In this case, it’s important that you save email attachments to a known, recoverable place on your hard drive so that you can find it afterward. Otherwise, you’re most likely going to have to redo a few minutes’ to a few hours’ worth of work.

All this said, the keys to version control are attention to detail, memory, and consistent processes. Keeping track of all of these can help you avoid some seriously nasty document hairballs.

About Bart Leahy

Freelance Technical Writer, Science Cheerleader Event & Membership Directior, and an all-around nice guy. Here to help.
Quote | This entry was posted in documents, editing, technical writing, workplace and tagged . Bookmark the permalink.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s