Take the 2-minute tour ×
Game Development Stack Exchange is a question and answer site for professional and independent game developers. It's 100% free, no registration required.

What type of support/format do you use to store and diffuse your game design documentation? Wiki? Doc files? Files in Repository? Shared folder? Google Doc?

Please provide pros and cons for each one.

share|improve this question
add comment

closed as not constructive by Nicol Bolas, Josh Petrie, Tetrad Feb 2 '13 at 1:36

As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or expertise, but this question will likely solicit debate, arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened, visit the help center for guidance.If this question can be reworded to fit the rules in the help center, please edit the question.

6 Answers

up vote 14 down vote accepted

I'm using Google Docs because all I really need is a text editor that's online. I can collaborate with people online with relative ease and I know my information is secure there in case my computer crashes.

Another option worth looking at is using Dropbox. Drop a Word document in there and you instantly have a collaborative environment with version control.

share|improve this answer
5  
P.S. Google Docs is completely AMAZING for real-time collaborative editing as of the recent (mid-September, I think) update. Dropbox, on the other hand, doesn't have conflict resolution (it renames a conflicting file, which can create even more confusion) so it's pretty terrible for simultaneous editing of files but great for backup and sharing/non-simultaneous editing. –  Ricket Oct 12 '10 at 15:53
    
Is there a way to have company-local (as company-server installed) google docs? –  Klaim Oct 12 '10 at 18:54
1  
@Klaim, if you get google Apps for your domain you can. google.com/apps/intl/en/business/index.html –  Noctrine Oct 13 '10 at 3:14
4  
Noctrine, it's still hosted by google. It just appears on your domain courtesy of a CNAME entry. If you require the data to be physically on your local network, this will not work. OTOH, unless you require a security clearance to work on your "game", the latter requirement is usually more an indication of paranoia and megalomania than anything else. –  drxzcl Oct 13 '10 at 7:51
1  
Yeah I already know for domains (I already have several google apps for my domains) but lets say you don't have access to the internet but only to a local network? –  Klaim Oct 13 '10 at 9:07
show 4 more comments

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.

share|improve this answer
add comment

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.

share|improve this answer
    
evernote.com is also a possibility for people who want a free alternative to OneNote. It has a web client and clients for various platforms (desktops, phones) and stores all your notes "in the cloud." I think it has collaboration features too, but they may be premium. –  CodexArcanum Oct 13 '10 at 15:21
add comment

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.

share|improve this answer
add comment

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.)

share|improve this answer
1  
All of your Cons are really a non-issue if you're using Confluence, with the exception for hosting which isn't free unless you host it on your LAN server and allow others to join via DynDNS or similar service. –  LearnCocos2D Oct 13 '10 at 8:23
    
Funny thing is, we used JIRA for our project. I guess either nobody considered Confluence as well or perhaps the cost was too high. I upvoted your answer anyway. –  Kylotan Oct 13 '10 at 10:21
    
Wiki-based design documents... Please, please... Don't. –  Laurent Couvidou Jan 29 '13 at 10:59
add comment

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.

share|improve this answer
add comment

Not the answer you're looking for? Browse other questions tagged or ask your own question.