Document Management using Subversion

Dom:

“I’d like to see a post on uses of SVN on a home computer, like document management, multi computer syncing”

This is the process I’m currently pushing for where I work. For all documentation I receive on projects I have to work on. I think it works well for all non source code documentation, but I have a feeling there will be mixed opinions. So lets see how we go…

We use Subversion to track changes that we make mainly in source code. These are plain text files, 90% of the time human readable. Using diff tools it makes it really easy to spot what has changed between versions. However a lot of documentation is written in proprietary formats which are unreadable to humans (Microsoft Word for example). You could just check these into Subversion, but you are losing a lot of the benefits you would normally gain from version control. Unless you were going to write very detailed comments for each revision, you would only be using Subversion as a glorified backup system.

My suggestion is this:

Write your documentation in a simple way, in plain text. This doesn’t mean you have to start writing everything as .txt files using notepad, but you could. A more serious suggestion is to write your documents in html. This is a plain text format, which allows very creative layout and presentation. I’m not suggest large complex websites, but just very simple <p> and <h1>’s, with the option of adding tables and images where needed.

Using a html format you will easily be able to see which sections of writing have changed between versions, and you will lose very little value in presentation. After all we all know that good documentation is about accuracy and clarity, not fancy word art.

You also get the added bonus of having a file format that is 99.9% viewable on any platform with any operating system. No more “My version of open office wont open your version of MS Word”. This is a very important consideration as you move to larger multi location teams.

I’ve seen some corporate repositories separate their source code and their documentation. I think this is a bit silly, personally I always advise it to be added right next to the source code and other resources. For example:

MyProject/
   docs/
   lib/
   resources/
   src/

To answer the second part of Dom’s question. If I want to sync with the server, I just do a svn update. This will give me the latest version which has been committed to the repository.

About this entry

You’re currently reading “Document Management using Subversion,” an entry on Svn-Checkout.co.uk

Published:
22.01.08 / 5pm
Category:
documentation, subversion