Managing Document Revisions using Subversion

By: Hal Warfield
Submitted: 2007-01-17 15:15:19
Print this article | Tell a friend | For publisher |

Rating:

 

Have you ever wanted to tear your hair out over revisions to a complex document or proposal?

We recently worked with a team responding to an RFP (request for proposal) from a large state agency. The RFP itself was nearly 100 pages long. The proposal responding to this RFP would be in excess of 150 pages. Its preparation effort required input from workgroup members scattered from San Diego to Charlotte.

Up to this point the company had done many long, detailed proposals. Their products were complex and involved technology components, civil works (concrete, drilling, boring), and network infrastructure, each of which had to be spelled out in detail.

The proposal development method was "blunt" (I'll say blunt rather than "crude.") In an era of instant messaging and conferencing systems, for _this_ task draft copies were sent back and forth to team members via email or, when the proposals began to top 15 megabytes in size, via an ftp (file transfer protocol) transfer to and from a shared server.

What's wrong with that? Even with smaller proposals they began to face confusion as the proposal developed. A phone conversation from two geographically separated team members might go something like this:

> HERE: "I just changed the executive summary and added the pricing section. I renamed the document 'proposal-1.2.doc' and emailed it to you. When you get it look over my changes and add your integration section and send it back to me."

> THERE: "Okay, but I had already renamed my working copy to version 1.2 last night."

> HERE: "Well then, open your copy, rename it to version 1.2.1 and send it to me that way. Which sections did you change?"

The person responsible for ensuring each set of changes was copied and pasted into the right places had many different pieces to keep up with, and the process didn't always go well. Arguments about who had made the most recent change and which document it was in were common.

An online search of ways to control this kind of version confusion revealed some additional confusion of its own. One system recommended for proposal writers includes building a tracking database to log information on sections and changes, which doesn't really change the process; it just makes one person really busy keeping up with changes.

With the approach of this large RFP, something had to change. The proposal required text, graphics, photos, drawings, and spreadsheets -- all properly tabbed and organized.

This is where we introduce [Subversion][svn]. Subversion is a revision control system designed by and for programmers to keep close tabs on multiple contributors' changes to large numbers of source files involved in most programming projects. Subversion is "open source" (OSS) software: software whose code is freely available to all ensuring its verifiable quality, that allows no vendor lock-in, and that often has the upfront benefit of no cost to purchase.

Subversion allows a remote user to "check out" a working copy of a folder from a secure repository. A secure repository can be thought of as a password-protected data warehouse where files are stored and managed. It may reside on your local drive, on an internal network, or be stored at a remote Internet provider. Subversion communicates with the repository through SSH (secure shell) which means access can be tightly controlled and that the data transfer is encrypted for safety.

You check out a "working copy" from the secure repository onto your local drive. From that time on you can add, remove, and make changes to your working copy content. Each time you "commit" these changes back to the repository, everyone working on the project -- no matter where they are -- has access to them immediately.

The beauty of this system is that multiple users can modify their working copy documents then commit those changes. By clicking on your working copy you can "update" and integrate everyone's changes into your working copy.

Additionally, Subversion encourages use of log messages -- descriptive text you add as you "commit" each round of changes. This log text works well as succinct, searchable documentation of changes made in the content being committed.

As I said before, Subversion was designed for programmers to track changes to their code; we had to find out if it would work with complicated Word and Excel documents.

It worked flawlessly -- team members added detailed graphs and charts, mechanical drawings, and site photos, then simply committed those changes back to the secure repository with a few clicks.

Each team member would occasionally right click his working copy folder and "update" his working copy, which retrieves and merges everyone else's changes into it.

As a result the proposal came together much more smoothly. The final result was over 150 pages that had to be printed and written to CD, nine copies each. Because the final document was a seamless whole (due to the subversion process), the production went quickly. Prior to this method, the proposal might end up being made up from a number of documents 'shoehorned' together.

Subversion can work for almost any group that produces documents, with multiple inputs by workgroups that may be separate geographically. This could include proposals, contracts, statements of work (SOW), or even a collaboratively written book.

Article source: Expert Articles