Subversion + WebDAV + Wiki = Cool. Fact.

Following on from yesterday's post about Confluence, I've been thinking how to get the same sort of workflow going for images, screenshots and designs - basically, stuff that isn't text.

A lot of our projects start life as Visio diagrams. A couple of us use Visio to actually put them together; everyone else has the free Visio viewer plug-in for Internet Explorer which means they can browse and view our work but can't edit it. Which is probably a good thing. Likewise, most of our designs start life as PSDs, and we always seem to end up with a couple of random spreadsheets full of data that isn't clean enough to import into the actual project DB yet but which is too important to ignore.

There's this principle in software engineering - Don't Repeat Yourself (DRY) - which basically means if you do something, do it exactly once, so that if it changes you only need to modify one piece of code. I think it's one of the absolute core principles of writing maintainable software, but I also believe the same principle is equally applicable to documentation, configuration - in fact, anything that involves manual intervention when changes are required. If I create a class diagram, I want to maintain a single master copy of that class diagram and, in a perfect world, any documents or pages that refer to it should be smart enough to always refer to that master copy.

We use Subversion as our version control system, but the principle of update-merge-edit-commit applies pretty well to almost any resource in a collaborative development process - there's even folks out there who keep their entire life in Subversion. So...  assuming we're keeping all our diagrams, designs and documents in Subversion, how can I link a page in our wiki directly to the latest revision of a document inside the repository?

Turns out it's pretty straightforward, mainly because other people have already built all the hard bits.

The key to all this is an Apache module, mod_dav_svn, that's part of Subversion and exposes your Subversion repository via WebDAV.  Since WebDAV is an extension of HTTP/1.1, that means you can use pretty much any web browser to navigate and view documents in the repository.

We already had Subversion up and running, so to add Apache and the WebDAV module I just followed the Apache install instructions in the Subversion book.

One thing to note - Subversion on Windows will not work with Apache 2.2.x; the mod_dav_svn module isn't compatible with this version and will give you warning messages about "mod_dav_svn.so is garbled". You'll need to install the latest version of the 2.0 series (2.0.63 in my case), and you'll also ideally want to disable IIS or any other web server on the box that's hosting your repository so that Apache can use port 80 on the server's primary IP.

Once it's all up and running, next time you're editing a Wiki page and think "hey, I really want to link to the Visio user experience workflow diagram here" - easy. Just point the link at the full URL of that diagram inside your WebDAV repository - something like

http://my.subversion.server/svn/myproject/docs/workflow/User+Experience.vsd

I think the real advantage of this approach is that you're not constantly exporting Visio docs as JPEGs and uploading them to the wiki - that's high-maintenance, and there's never any guarantee that the JPEGs in the wiki actually reflect the latest state of the original diagrams.

With this approach, you just run svn update locally to get the latest set of documents, make your changes, and  run svn commit - just like checking in regular code. Any links pointing to your document via the WebDAV repository will always point to the latest version - and you never have to worry about maintaining multiple copies.

Confluence, the wiki engine we're using right now, should theoretically let you embed images that are hosted under WebDAV - so your tags end up something like

<img src="http://my.subversion.server/svn/myproject/docs/homepage01.png" alt="Homepage design (01)" />

as well as just creating hyperlinks to documents - but Confluence doesn't seem to like that right now.

UPDATE: It's possible to work around this bug by inserting the image URL directly into the Wiki markup surrounded by exclamation marks - !http://www.myserver.com/image.jpg! will display image.jpg from www.myserver.com as a normal IMG tag. Not quite as streamlined as drag'n'drop but it does work.

As an aside - right now we've got a build server running on IIS, a wiki engine running J2EE on Tomcat, and Subversion hosted from Apache, but the resulting environment actually feels more cohesive and integrated than most of the IIS-only setups I've played with over the last year or so. Personally, I think this is because the quality of the apps themselves - Apache, Subversion, Confluence, FinalBuilder, CruiseControl.NET - is so high that the underlying platform is basically irrelevant in day-to-day use. What's been really apparent getting this configuration up and running, though, is that the package authors (or vendors - never quite sure what you call the people you get free stuff from...) have put enough effort into the installers that the platform doesn't really matter at installation time either. Sure, it means we're running three different web servers right now - but they seem to be working, and maybe we should be thinking in terms of eggs & baskets instead.