I recently made a post on this issue over at Gamedev.net, and thought I’d clean it up a bit to post over here, as I think it’s worth talking about. Designers are often looking for new and better ways both to create and present their design documents, and rightfully so. Just as programmers may try different languages, techniques, tools, and IDEs, designers should be looking at better tools and methods to allow them to capture their ideas, organise and prioritise them in a sensible way, and to present them to a variety of audiences, perhaps the most important of which during the implementation phase of the project being the programming team.
Our team used a Wiki for the current project, and while this choice carried several benefits, it also had several shortcomings. The positives barely need expressing to anybody familiar with Wikis – they allow collaborative work, ad-hoc reorganisation, easy cross-referencing, automatic outlining and table-of-content generation, built-in version-control, etc. Therefore I will expand upon the negatives. None of these problems are fatal, but it’s easy to fall foul of them without realising it if you’ve not used one before. So here’s what I learned from my personal experience.
Every page should be categorised. Use sub-categories if they make sense. In this modern world of tagging things rather than grouping them into hierarchies, or following Google’s “search not sort” mentality, it’s easy to overlook the categorisation. Don’t do this! Otherwise there can be parts of the design that nobody sees. Nobody is going to recursively click every single link in the document, nor is anybody going to exhaustively read every page that is returned for any given search term.
Instead there should be discrete categories and anybody who needs to understand a certain aspect or feature of the game should quickly be able to see a clearly marked subset of the document that is relevant to them. Following from this, if you have a design team who are collaborating on the document it is useful if individual designers take sole responsibility for certain categories, ideally the features they designed or primarily work with. Each category should stand alone as a fairly complete sub-document, with external links existing just for reference. Otherwise you end up needing to be familiar with the whole doc to get anything done, which means you’ve lost most of your benefits over a normal linear document.
Be prepared to produce hard copies of the categories. Obviously this is not really an issue if you work remotely. But if you share an office, being able to print off parts of the document conveniently is vital. A hard copy is much more convenient to use in meetings, for writing notes on, etc. Nobody wants to be pulled into a meeting about Feature X when there is no possible way you can bring all the specifications for Feature X with you to refer to. And if you can’t refer to the documents, you tend to end up designing in parallel to them. If you can’t print off part of the document, you tend to find that people start designing features outside of the wiki for convenience purposes. And you don’t want that because suddenly your design becomes ephemeral and ethereal – an email here, a JIRA/Bugzilla comment there, a note on a pad somewhere else, because everybody was writing without direct reference to the original document.
Ensure that pages can be locked against edits, and are when appropriate. Programmers will follow the specification as closely as they can and will clear up ambiguities with the designers as needed. But the very nature of expressing s0ftware in natural language means that occasionally a designer will write something and the programmer will implement it in a way that fails to catch the spirit of what was written while nailing the syntax 100%. This is unfortunate but is essentially a problem that designers and programmers can work through, the designers learning to be more explicit and less ambiguous with their descriptions and the programmers learning to spot situations where this might be the case. A worse problem is when designers are free to work and rework their design during implementation. A collaborative document like a wiki makes this far too easy and tempting to do. Designers, wanting the best for the game and to provide the best service to the programmers, have a tendency to go back and ‘improve’ and ‘clarify’ their designs after you’ve already started or even finished implementing them. They think they’re being helpful or diligent, but actually they can cause a major discrepancy between design and implementation. Of course, in their head, the discrepancy was already there, but in the programmer’s head, the design has appeared to change significantly. When this happens during implementation, it can be frustrating to the programmer and cause some work to be scrapped and rewritten. Worse is when it happens after implementation, and the first that the programmer hears of it is when the QA department find that discrepancy and file a bug against it, implicating the programmer for not following the design.
Once designs are given to the programmers to work on, lock the page, and force future amendments to go through an approval process. The history and revision control feature is not enough for this. QA are not going to rigorously compare the coder’s source control commit times to the designer’s wiki revision history when noting a discrepancy between ‘The Design’ and ‘The Implementation’. More than the others, this is a management issue rather than a technology issue. The same problem could conceivably happen with any design doc. However the wiki technology makes it much easier to make little adjustments here and there without anybody noticing until the damage is done.
Ensure that all pages have one owner. A good design is often a big design. In Wiki terms this can mean tens or hundreds of separate pages. As the project moves forward, some features grow, some shrink, some are removed or replaced entirely. Obviously all these changes should be signed off with the implementors as mentioned already, but then the document must remain up to date. On a regular basis coders and QA staff will use the wiki as a reference, sometimes going back to a page they’ve not used for weeks, or using the search functionality to uncover the relevant page. What is critical therefore is that what they find must be relevant and pertinent to what they’re working on. Otherwise their time is wasted: at best, they have to search again (and again), and at worst, they take some action based on this outdated design which wastes their time and potentially that of other people too.
For this reason, every wiki page should be owned by a person on the design team, and that someone should keep the page updated in sync with any changes made to the design so that the information is always correct. If you have the information categorised adequately then each category can have an owner and this becomes quite simple. But without someone being accountable, it’s assumed that someone else will keep it up to date, and this won’t happen because nobody will exhaustively check every page to see if any are out of date. If it’s not practical to have a single owner for a feature or category (as might be the case if it is being co-designed by 2 people, for example), designate one of them as having responsibility for the wiki pages.
Be disciplined regarding scratch-pad, discussion, or brainstorming pages. Wikis are a good middle ground for discussing and evolving a design. They are more convenient than email in terms of having all the information in front of you, and less time-consuming than meetings where all but one person is doing nothing but listening. Unfortunately this means that the game design document can end up with annotations, discussions, vague ideas, and other noise scattered in among the signal. This can make it hard for programmers to see what is the agreed design and what was just discussion and ideas relating to the topic. Sometimes the problem is in the other direction and key design decisions are left stated in these discussions and not migrated to any clear specification area.
Use a separate namespace if your wiki provides such a thing to keep the normal searches free of this noise. The MediaWiki ‘Talk’ or ‘Discussion’ pages are a good way to handle this, leaving the main pages with the official docs. At the very least flag the page with a big disclaimer message or template that quickly tells programmers or QA that the content of this page is not gospel and is subject to change without notice. Designers should migrate authoritative information from these pages to the proper specification pages as appropriate.
Hopefully that is all useful to someone!