RE: [GD-Design] Design Documents

[Sellers, M. <mse...@or...>]

Albert Reed wrote:
> We use Word for our non-technical design documentation and 
> have yet to really run into problems. However, for the most 
> part only one person ever edits a given section of the design 
> document at a time. Everyone contributes ideas, and someone 
> who's a good writer sticks them into the doc. We have it 
> broken into several sections and then exported into HTML. The 
> doc right now is about 70 pages. To keep people up-to-date we 
> just paste changes onto the homepage of our internal web 
> server for all to read.

I should add given my earlier comments that we use "Word + Perforce" not
just word by itself.  Word is great for docs, and Perforce (or your favorite
source control tool) manages the versioning/branching/merging issue.  We
keep our docs accessible from an internal web site as well, so you don't
have to check them out to view them or anything.  

> The reason we went with this solution was simplicity. If you 
> don't need to have multiple people editing the same section 
> of the document at the same time, then you won't run into any 
> problems. Saving as HTML and putting it onto a web server 
> works great for us, since it's super-easy for programmers to 
> look up the information they need just by browsing around on 
> our internal server. There's no setup time, and file->save 
> as... Is about as easy as it gets.

Yep.  And simplicity wins out *big* in areas like this.  Tools that are
way-cool but at all cumbersome to use just won't get used; people will find
it easier to circumvent the tools instead.  (FWIW, ours is a large team
project too, so this doesn't seem to have issues of scaling to support a
large project or a large team.)  

Mike Sellers