Most developers today seem to understand the benefits of a source code version control system, and its ancillary uses in tracking changes to project notes, documentation, and other non source code files. Version control generally makes sense even if you’re the only person working on the project; once set up it’s fairly trivial to use, especially if it integrates with your IDE, and it’s often very useful to do diffs on old versions of code, and to be able to split off release and dev versions, and things of that nature.
There aren’t really any good excuses for not having a version control system in place, especially when you can get something like SubVersion (SVN) for free. However, in the real world, there are environments in which there is resistance to version control, or at least to extending it to documentation. Yet, if you’re not the only person to maintain the documents, there needs to be a system in place to prevent overwrites and conflicts. I’ve had two projects recently where this was an issue.
Sometimes you just have to pick your battles — maybe the other people with edit rights don’t understand source control, and don’t want to take the time to understand it. People usually fear what they don’t understand.
If you are dealing with a small number of people who are reasonably computer-literate and somewhat disciplined in their approach to work, here’s a simple ad-hoc system I’ve worked out that has been successful for me.
Let’s say that you have a folder on a share someplace that you call Documentation. It contains several Word documents documenting the system you’re working on and the business rules it implements. You might create the initial draft but parts of the documentation are subject to edit by others — domain experts, etc.
Simply create a CheckOut subfolder within Documents, and then within CheckOut create a folder named after each person with edit rights. Then get buy-in to the following procedure:
- In order to check out a document, first see if it exists in the Documents folder. If it does, move it to your personal checkout folder, then copy it to your local hard drive to work on. If the document doesn’t exist, you know someone else has it checked out, and you can find out who that is by seeing what checkout folder the document has been moved to. Documents in the chekout folders are for read purposes only; they can’t be modified until the “owner” puts them back in the Documents folder.
- To check a document in, copy your edits back to the Documents folder and delete the original in your checkout folder.
It’s far from foolproof, but it’s simple, non-threatening, and cost-free. It doesn’t require that anyone learn anything new, including figuring out Word’s proofing features, which is a kind of crude version control in its own right.
The main understanding you need to have with all the participants is that if they forget or “cheat” then their work is subject to being overwritten by someone else, and they have no right to whine about it. When this happens to someone once or twice, they sharpen up in a hurry. In practice, even that is not usually a big deal because often, individual changes are fairly minor.
A downside is the “PITA factor” — this approach creates a certain amount of intertia over making a quick change on the spur of the moment. Of course, if that begins to wear on people you can always mention that they could leverage the document proofing / review features or place the document under version control. ;-)
Of course you can vary the above … files can simply be renamed with a prepended “(Checked Out by XX)” to check them out. This has the advantage that you can see all the documents at a glance, including which ones are checked out and who has them. The details don’t matter, you just need an agreed convention.
