In his postmortem for SWAT3, author Jim Napier said that one of the things his team at Sierra did was keep design documents distributed throughout the company in the form of e-mails in people's inboxes. "In the future, we should keep all design documents in a central location and keep them up to date," he said.
Centralizing the location is very easy to do.
Wikis have spread like a virus throughout all of civilized society, so this article may not be useful to anyone. But as long as there's someone out there reading this who hasn't been infected yet, I'll feel like I did my part.
Scott Bilas of Gas Powered Games turned us on to using the Wiki as a collaborative documentation tool. The product he pointed to and we've used ever since is OpenWiki, which you can download for free from http://openwiki.com/. If you've ever tried to set up an internal website to document your project, and failed because it was just a little bit too much work to add or change content, then this is for you. To add or change content to OpenWiki, you double-click.
It was very easy to install. I set it up on my machine as a test, and it told me as I went what the various components I'd need to download from Microsoft were to get my machine up to spec.
When installing it on a server, it was as easy to install as WinAmp. Which means you barely have to have any influence at your company at all to set one up and get the team to start using it.
The kinds of things we keep in our Wiki include the entire technical design document (TDD) -- which consists of a small spec (a sentence to a paragraph) for every feature in the coder schedule -- and various FAQs for how to use Perforce, run the game, and our check-in/submit validation procedures. But anything is fair game. As Scott pointed out, it spreads like a virus.
Some people may be shocked that I leave our TDD up where anybody could edit it. Somebody could just come along and decide they like their design better, for example, and change the permanent record. I've found that this is not a problem. First of all, people are not that bold. I have yet to see someone "commandeer" the Wiki in this way. Occasionally someone will put in an initialed comment, but that's about it. Second of all, the entire history of the Wiki is stored on the server. You can watch the recent changes and make sure nobody's doing anything sketchy.
It was slightly difficult to print out the TDD for Activision and Sony when they needed it, but with OpenWiki it is possible to make a master document that contains several sub-documents. If they're nested that makes it even more problematic.
We used to use flipcharts in our design meetings to take down notes everyone could see as we go. Now we have a PC hooked up to a large television open to a web-page. The scribe can simply add notes to the Wiki as we go. This means nobody has to spend time transcribing the flipcharts to a design doc at a later date.
Wikis do not solve the biggest problem with design documents: nobody reads them. I used to try sending out links to new Wiki pages I had written or changed, but that didn't work. There's something about e-mails that makes them get read, at least by a few people, if they're not too long. I've resorted to documenting in the Wiki and copying the document to an e-mail, asking people to please read it and raise red flags if they see any problems. When people are reading a document looking for errors, they're a little more likely to actually assimilate its contents than when they're just skimming it.
As
far as keeping a design document up to date goes, the Wiki makes
it easy, but people still have to do it, and so it still doesn't
get done. I, personally, don't have a problem with this. Whether
you like it or not, there's a time when the product becomes its
own document, and your publisher is going to be looking at that
and making suggestions. They're not going to check the design documents
to see if something is 'as designed' or not. You'll wonder if they
ever read the specs in the first place. So spending a time maintaining
a document does not seem like time well spent, at least to me. Maybe
things are different with other publishers; maybe they have test
plans that are built from design docs, in which case it would be
essential to maintain. In which case, Wiki up.
______________________________________________________