| |

Don’t let version confusion destroy your writing process

The most fundamental principle in writing is actually . . . version control?

It’s an unwritten rule. Like changing your underwear every day. And if you violate it, you are a barbarian.

This is the least sexy writing advice ever. But if you and your collaborators don’t share a common understanding of version control, you’re in for a world of pain.

What is version control?

Version control is the principle that at any point in time, a document, or portion of a document, has one owner. That owner is responsible for its content. Others may comment or make suggestions, but the document owner is the only one making changes.

If you work alone and never collaborate with anyone, you could ignore this. But in practice, all professional writers work with editors and reviewers. Many have collaborators. So in real life, version control matters to them.

Why is it important?

Because violating it will make you crazy.

If you and another person are making changes to the same document at the same time, your writing will lose coherence. You will inadvertently introduce redundancies and contradictions into your work.

You’ll go to save your work and get a permission violation, because somebody else has already saved it in a different version.

In order to track down what has happened, you’ll need to resort to version comparison tools and untangle the history of the edits. This is pointless rework. It is waste. It is infuriating and it should be, because it is repairing a self-inflicted problem you could easily have avoided.

Worse, it creates distrust and blame, which in the end will destroy any writing project.

Version control is easy, if you’re systematic

Some sophisticated writing shops have check-in check-out workflow systems, similar to what software engineers use to manage code. Most shops don’t have rigid rules like this. But regardless of how you implement version control technically, the key is process and custom.

First, process. Any piece of writing in a collaborative environment should have a process associated with it. For example:

  • Primary author writes, turns document over to copy editor, gets document back with edits, makes revisions, turns in final copy.
  • Primary author writes chapter, collaborator reviews, collaborators discuss differences, primary author revises, repeat until satisfied, turn over to copy editor, respond to copyedits, complete chapter.
  • Writer creates draft, sends out for multiple reviews, collates reviews, revises, sends to copy editor, responds to copyedit, completes.

You would think any workplace with writers in it would have a process like this in place. And most do . . . in theory. But 32% of business authors complain that their review process works poorly.

While processes vary, what matters is that you have — and document — a model process. Then each participant knows what’s expected of them.

Implementing version control with Word or Google Docs

A few simple tools and conventions can help manage versions.

First, develop a naming convention. For example, in my books, a document name ending in v1 is a first draft chapter, v2 is second draft chapter, and CE is a chapter ready for copy edit. When I am editing and I return a document to the author, I add “jb edit” after the original filename. That way they can keep track of their original as compared to my copy.

I always use redline edits, using track changes in Microsoft Word or the suggesting mode in Google Docs. People who edit others’ work without the redline feature are not fit company. People who edit with red pen on paper are barbarians. If you don’t know how redlines and comments work in Word or Google Docs, learn how, or you can’t call yourself a writing professional.

Even though emailing drafts back and forth is inefficient and can create confusion, it is often sufficient for simple projects or workflows. Better is a well organized shared document store (in Dropbox or Google Drive, for example) that everyone works from.

Despite Microsoft Word’s collaborative editing features in its latest versions, people still generally open documents, edit them, and save them before asking others to read them. This helps maintain the concept of a single canonical version of the document at any given time.

Google Docs can be problematic unless your collaborators are very disciplined. In a recent book project, my two coauthors and I used Google Docs — I wrote chapters and they commented in suggesting mode. This worked well because they could see each others’ edits and my comments on those edits. But it worked only because they used the suggesting mode and never tinkered with the text without leaving a visible trail. This required me to trust them.

(Because of Google Docs’ version history, you can track down all the changes in a document and who made them, but if you find yourself doing that, somebody has violated the version control rules.)

Most people never have these conversations. That’s a mistake.

If you ever find yourself hopping mad at a collaborator for messing with a document when she shouldn’t have, the root cause is a conversation you should have had earlier.

At the start of a project, work out a process in which only one person owns a document at any given moment.

Figure out how you’ll get comments, edits, and suggestions from people who don’t own the document — typically through a clear redline edit process.

Figure out how you’ll determine when a document is done enough to get to the next stage, and who has to approve it.

It’s a short, simple conversation that save you a lot of pain in the future.

Change your underwear every day. Don’t put coffee grounds down the garbage disposal. Don’t microwave fish in a shared workspace. And don’t violate the version control conventions you’ve set up. Because, after all, you’re not a barbarian.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.

5 Comments

  1. This is excellent advice, Josh. And version control is indeed a basic “hygiene” practice. I have inhaled the sulfurous fumes of Version Control Hell too many times. It’s a continual surprise to me that more business people have no idea how to manage redlining in Word docs, even when I send them drafts with “mark changes” turned on.

  2. Your discussion of version control is very valuable. But there is at least one way for multiple authors/contributors to work on a single document at the real time, and everyone can see each person’s changes because each person’s changes are shown with a different background color. It’s Etherpad, found at etherpad.org. It’s open source, so anyone can use Etherpad without cost.

    Etherpad, to shamelessly quote Wikipedia, “is an open-source, web-based collaborative real-time editor, allowing authors to simultaneously edit a text document, and see all of the participants’ edits in real-time, with the ability to display each author’s text in their own color. There is also a chat box in the sidebar to allow meta communication.”

    Google acquired Etherpad in 2009 and almost immediately released it back into the wild, where others picked it up and keep maintaining it. I’ve always thought Google Docs made a big mistake not incorporating Etherpad’s very cool collaboration technology into Docs.

    FWIW, I have no involvement with Etherpad or the Etherpad Foundation. I just happen to know about it.

  3. Sound advice, as usual; thanks. A few thoughts:

    Editing software has an implied design difference between “track changes” and “suggesting mode” features. When collaborating, the former seems to imply asking for forgiveness and the latter like asking for approval.

    At Angel City Press our editing team finds that suggesting is more compatible with our draft-edit-proof processes. (And since each suggestion creates its own comment thread in Google Docs, it is easy for a document’s owner-editor to reply to a suggested edit without accepting it when something’s not quite right.)

    Because document ownership determines control, we take advantage of it in our work flow. For early drafts, it is just fine for the writer to have full document privileges — even ownership. We are watching them write, maybe guiding a bit. Their “handing in” a document for editing means passing its ownership to over to us — at that point we restrict their access to suggesting mode and put on our editor hats.

    Access is controlled per document; for us this usually means one document per chapter, and more for front- and back-matter sections. We use a one-page “elements” outline document (it looks like a table of contents) with links to all the others.

    This is far from a work-flow system, but it has served us well.