Don't just put your documentation in source control

In the GS04 course at UCL I told the students to put everything into source control; not just source code but also things like documentation and configuration files.

That's all very well, but my current project at work has made me realise that you can do even better. You should not just put your documentation in source control, you should serve it from source control.

On my current project we have all our documentation served directly from our subversion repository, mostly as html.

What about Wikis?

I used to be a big fan of having a project wiki.

A wiki can be great but:

1. they do have a tendency to get out of date easily
2. they can accumulate lots of garbage
3. they can be difficult to version control well (difficult to keep in sync with the project's source code repository - I know there are things like Trac but in a lot of companies you don't get to choose what systems you use)
4. if the project is abandoned for a long time, the chances are that the wiki might disappear (I've seen it a few times - moving to another wiki system and not migrating old pages) but the source code repository will be around for a long time (and if it isn't then you're screwed anyway).

Wikis still have their place - when collaboration with lots of people is needed, but for developer written documentation I'm happier to have it in the same source control system as the code it refers to.

Taking my own advice

I've updated my semi-abandoned project build-o-matic, so its web site is now served directly from its source code repository. It's now so much easier to update the web site (just edit and commit) that I might even get the web site up-to-date.

But there again, the World Cup is on TV today ...

Copyright © 2010 Ivan Moore