What type of document for game design? [closed]

Wiki

Pros:

• Latest version always accessible over web, from off-site, etc.
• Fairly easy to use (if you steer clear of those with a trainwreck for formatting like MediaWiki, that is)
• Automatic indexing, searching, easy categorisation
• Easy to attribute changes to people and to make them accountable for changes
• Supports linking and makes it easy and effective to factor out details
• Can link to wiki pages directly from internal bug reports and other correspondence, making verification of a bug very easy
• Version history and revision control typically built in

Cons:

• Sometimes TOO easy to change (*see below) and requires discipline
• Pages can get out of sync when edited in isolation (often no 'global search and replace', for example)
• Pages get orphaned or superceded and left as potential minefields for coders later. ("What do you mean we're not implementing that any more? It's still in the design wiki!")
• Syntax can be a little esoteric unless you get the right package
• Have to arrange hosting, or accept what is available online for free
• No clear route through the document - how do you read it 'all'?
• Hard to print. Can you print it all out with one click? Can you easily print out everything relevant to one given feature in order to take it into a meeting? Can you annotate the digital version easily without obscuring the underlying document?

(* We used a wiki for one project and designers were always tempted to go in and 'improve' parts of it, even on features that had been signed off and sent to be coded up. Then when QA got to testing the feature, it would be a nightmare because often the design would suggest something different to what was actually coded, and it would take a fair bit of frustrating work to find out which happened first, the change to the design or the code.)

Text Files

On my current project, I'm using simple plain-text files in my "Docs" folder of the project, stored in the repository beside the code.

Pros:

• Documentation is kept close to the actual work, so its easy to find.
• Simple formatting means it is easy and fast to maintain documentation.
• Simple format also means there's little risk of losing documentation due to server crashes, file corruptions, etc.
• Absolutely minimal set-up time makes this a great start for single-developer or tiny (2-3 person) teams.
• Using version control means that changes are tracked, and often one can link changes in documentation directly with a change in the code.
• As easy to work with as text, so searching, editing, and so on can often be done with command line tools.

Cons:

• More than a couple of users and the document would get out of sync easily.
• No links, so either you use one grotesquely large document or several smaller but disconnected documents.
• Limited formatting and publication options (though conversion, such as through Markdown, is easy to do.)
• As easy to work with as text, so often the only way to get searching, advanced editing, and so on is to use command line tools.

It's not something you want to rely for any kind of team work, but the power of text files in the repo to let you get right to work should not be underestimated for the single-developer. Currently I use one document as a kind of overview/master-planner that contains the general design, a second document that acts as a ToDo-list of specific things the game needs, a third document as a loose bug tracker, and ancillary documents to elaborate on "feature x" as needed.

Don't use a document format/editor that's not multi-user capable (eg. MS Word, Open Office Writer). Only one person can edit the doc, and even with source control it's too easy to start working on an outdated version, and by saving that you basically destroy everything the other user(s) have done since the last time that user has updated his version of the document.

Shared folders are by far the worst solution and an absolute no go for any kind of asset that's supposed to be worked on collaboratively. You can never be sure that someone else is working on that file right now, or will do so in the next couple minutes. You also don't have change tracking and can't revert back to a previous version in case of a disaster (human error or human stupidity or human neglect).

Preferably use a Wiki, but one that's user friendly and is truely WYSIWYG. I personally swear by Confluence, which is also used in bigger game dev studios and is only $10 for up to 10 users and unlimited viewers.

Most other wikis (MediaWiki, TikiWiki, etc.) have the downside that they have a steep learning curve or are even practically unusable by non-technical personnel. Not that they couldn't learn it but they (rightfully) don't accept using a document system that's basically requiring you to write code like HTML. This is my pet peeve: Wikis that say they are WYSIWYG but all they do is insert the syntax into the text you're writing. That's not WYSIWYG!

The guideline for using a wiki is to put every heading on a seperate page, so you can cut the document into many manageable parts. Confluence offers features with which you can then aggregate all those subpages back into a single site or document, which can be exported to PDF for example.

I think One Note is a good option. It is something like a Wiki but with lots of rich text editing support. In addition to the standard desktop client which comes with Office there is a web based version with the Office Live suite. Honestly, I think the web based version, which is free, should be enough for most needs and when combined with Skydrive you have a pretty good system to collaborate on a live document.

For one of my open-source projects, we've been using (gasp) SharePoint to store documents and media. Managing users and permissions is pretty straightforward, and it has support for full version history. We've had the SharePoint site for about four years now, so there may very well be better options nowadays. However, it has worked out pretty well for us. It's hosted by a third party (for around $20/month), so after the initial setup there has been virtually no maintenance on our part. In addition to supporting document and image libraries, SharePoint has Wiki support, though I'm not sure how well it measures up against the more popular Wiki engines.