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:
- they do have a tendency to get out of date easily
- they can accumulate lots of garbage
- 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)
- 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).
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