I like the idea of using web technologies to deliver the document. Maybe have it in a local folder so it isn't public. Of course, if it is a company doing this, a wiki on the companies intranet would be easy to set up.

It should depend on your target audience I guess. If you're using it to raise capital then it'd make sense to pass it around as a word document, maybe a pdf, but you probably want it in a medium you can easily change and be able to print it. If, like you said, you are just putting something together for an internal dev team then yeah a wiki makes sense there. Trying to attract freelance/open-sourced help would benefit by using a wiki as well.

1. I always wondered.. is putting the "Um" in there meant as a veiled "Duh"?
2. Is it necessary?

1. Good point.
2. "Necessary"? Really, was even your question really "necessary"? To veil a "duh" as "um" is to be polite, while perhaps subtly pointing out the flaws in the thinking behind the post being replied to. It can be helpful to point out such flaws -- the writer being replied to can take that information and apply it to future conversations.
Political correctness can easily be carried too far.

I think it's obvious to anyone bothering to think about the context that "Is that necessary?" meant "Is it necessary to have that kind of attitude?"
By the way, speaking of "not necessary", what's the function of your contribution here? You purposefully picked out a small, inconsequential tangent to the conversation in order to interject your opinion on the usage of "umm"?

The important part of this thread had been handled sufficiently well.
Regardless of my being a mod here, my opinion is that I should be permitted to express my opinion.

I'm not fond of using Wiki or HTML, because they don't print well. At my studio, most people print their documentation, and poor print formatting can lead to unnecessary confusion.

I also don't believe in the single, giant "Design Bible" document. I used to be an engineer, so I know first-hand that most coders don't read large documents. Yeah, yeah, they should, but that's irrelevant... they don't, so unless that changes you won't get anywhere handing a programmer a 300+ page monstrosity.

My typical approach is to create many word documents (1-5 pages apiece, with a few longer ones for really big features) and organize them in a file tree (UI docs in the UI folder, Mechanics docs in the mechanics folder, etc). Final versions are in .PDF format to guarantee that they look the same to every reader (Word docs, in particular, get pretty nasty if everyone's not using the same version & view settings). Each document is intended to have a fully implementable feature written up in it: engineers should be able to write that feature purely by reading that one document. Sometimes features work too closely together and the engineer needs to understand both systems to implement one, in those cases I reference "Read document X for full implementation", but I find that with proper technique you can keep those sort of references to a minimum (in my last shipped game, I think the most "reference another document" links I had in one doc was two).

It doesn't have the hyperlink-browseability of a Wiki, but I have been thanked by multiple engineers for "not making them hunt for what's important". The docs tend to be short (1-5 pages is all you really need for most implementation docs - not counting any stat/tuning charts which should go in as appendices at the end), which also makes them very easy to "staple" to a user story on a SCRUM board (if you're using Agile development). My goal on my last project was to have a fully-implementable document for every user-story. I think I hit about 80%, which isn't too bad for an accelerated dev cycle, but I'm sure I could do better. The other 20% ended up being user stories that spanned multiple documents, which I don't really like).

I think for my next project I'll probably take that a step further, trying to hit 100% doc-to-user-story ratio (so every user story can just say "implement this doc to complete the task") and writing the Conditions for Satisfaction right at the front of the docs so engineers know when they can call a feature "complete" (instead of having to go through the whole doc making sure they didn't miss anything). I think this would make development much more efficient, and make the planning/team-organization process much faster (my least favorite part of development, so the faster it goes the better).

Anyway, my point with all this rambling is that the documentation process might be helpful to designers, but the target audience of your documentation are the engineers (and sometimes artists) who are implementing the game. So every decision you make about your documentation should revolve around them: making it as easy as possible for them to do their work, taking strain off management's shoulders from having to take corrective actions, and accepting that most engineers don't want to have to sift your lengthy backstory and mechanical writeups before they can code the savegame system.

I'm not fond of using Wiki or HTML, because they don't print well. At my studio, most people print their documentation, and poor print formatting can lead to unnecessary confusion.

CSS can cure all your styling ills.

I also don't believe in the single, giant "Design Bible" document. I used to be an engineer, so I know first-hand that most coders don't read large documents. Yeah, yeah, they should, but that's irrelevant... they don't, so unless that changes you won't get anywhere handing a programmer a 300+ page monstrosity.


....

Anyway, my point with all this rambling is that the documentation process might be helpful to designers, but the target audience of your documentation are the engineers (and sometimes artists) who are implementing the game. So every decision you make about your documentation should revolve around them: making it as easy as possible for them to do their work, taking strain off management's shoulders from having to take corrective actions, and accepting that most engineers don't want to have to sift your lengthy backstory and mechanical writeups before they can code the savegame system.

Not in all cases. The large bible-like document is for the development team but other documentation is for investors, partners, etc. so it'd be prudent to keep a copy for each target audience.

[quote name='JBourrie' timestamp='1306957745' post='4818409']
I'm not fond of using Wiki or HTML, because they don't print well. At my studio, most people print their documentation, and poor print formatting can lead to unnecessary confusion.

CSS can cure all your styling ills.
[/quote]
Seems like so much work to deal with markup languages, when Word is designed to do all that formatting for you. But maybe I'm just doing it wrong (not terribly web-development-savvy)

[quote name='JBourrie' timestamp='1306957745' post='4818409']
I also don't believe in the single, giant "Design Bible" document. I used to be an engineer, so I know first-hand that most coders don't read large documents. Yeah, yeah, they should, but that's irrelevant... they don't, so unless that changes you won't get anywhere handing a programmer a 300+ page monstrosity.


....

Anyway, my point with all this rambling is that the documentation process might be helpful to designers, but the target audience of your documentation are the engineers (and sometimes artists) who are implementing the game. So every decision you make about your documentation should revolve around them: making it as easy as possible for them to do their work, taking strain off management's shoulders from having to take corrective actions, and accepting that most engineers don't want to have to sift your lengthy backstory and mechanical writeups before they can code the savegame system.

Not in all cases. The large bible-like document is for the development team but other documentation is for investors, partners, etc. so it'd be prudent to keep a copy for each target audience.
[/quote]
Right, we often have to combine the docs into one big one for partners, but sometimes it's two different documentation chains (abstract, business-minded pitch docs VS implementation docs). Just depends on who wants to see it.