Building Living Specifications

Producing new functional requirements for each project is evil and should be illegal, and punishable by death or working as a tester [1]. It is a basic cause of incoherent system, lack of holistic system thinking, and a lack of coherent documentation to support testing.

We've all had the experience of trying to understand the behaviour of a system and wading through reams of the original specification, change requests, and series of follow-on project specs, so why do we willing perpetrate this mess?

Probably a few main reasons:

1) The model of monolithic documents being prepared, signed-off, and developed against encourage this beahviour.
2) In the short-term it's the fastest way to get your individual project over the line
3) It's how we've been taught to do it
4) When we do decide to do something about it, we don't get angry that we're documenting badly, we get angry that we're documenting _at all_, and we implement some messy mix of agile and waterfall.
5) Wanting to have "all the information in one place" for decision makers (Which is a really valid point)

So what can be done about it? I'd generally propose a few changes that don't involve a massive change to current practices.

1) For new projects try to split out the project ephemera from the functional design that will be re-used.
2) Instead of having a singel plave for all project documentation, have a seperate place for storing project documetnation, system documentation, and process documentation. This reinforces that they should be treated seperately.
3) Gently ease into some business architechture questions, because if you're not using projects as the basic unit of information, you're going to need soemthing to replace it, and a system centric-organisation is a pretty poor substitiute.
4) Get some soom document/knowledge management systems. Shared directories will not work if you're moving towards lots of smaller documents. Consider Sharepoint as your first stop, and moving towards a Wiki and a Modelling tool in the long tem.

All of these mitigate against most of the objections I raised earlier, but they still don't give you the "single view" of the changes you're making for the project. Unfortunately there's no magic-bullet here. The more solution centric you make your documents, the less project centric they become.

Ideally you could mix-and-match content together into dynamic documents. But there's just no good tools for that, confluence is closest but really isn't there yet. There's a good summary of why up at http://confluence.atlassian.com/display/DISC/Using+Confluence+for+professional+documentation.

[1] Nothing against testers. It's just that most BAs hate working as testers.