Wiki Solutions
There are lots of different Wiki solutions to choose from. Wikipedia
has a good list going, in fact.
If your main factor for deciding on a Wiki solution is cost,
there are plenty of freeware options. Just keep in mind that you get what you
pay for. They are feature-lite and lacking in support. I'd encourage you to
explore this if you're just experimenting with Wiki. However, I'm sure you'll
find that once you're committed, your desire for features will drive your
decision more than cost.
A major consideration should be ease of customization. If you
or someone on your staff is comfortable in a particular programming language --
CSS, PHP, Perl, Python or Java -- then you
might want to choose a solution that is implemented with that language.
However, the more powerful Wiki solutions will present a non-programmer
interface for adding features via plug-ins and macro editing windows. In the spirit of open-source collaboration,
there are hundreds of Wiki plug-ins and macros out there that may give you the
specific features you want.
The examples I use in this article use TWiki and Confluence.
Actual Wiki syntax can and will vary significantly with each Wiki.
Pros and Cons of Wiki for Game Design Documentation
The pros and cons below are based on using Wiki versus more
traditional Word and PDF documents.
Pro
|
Con
|
|
Collaboration:
-
supports multiple editors working
simultaneously on different topics
|
Design Mayhem:
-
too many cooks in the kitchen can lead to
disjointed design and warring editors
|
|
Browser Friendly:
-
organized into branches with link pages
-
uses labels for searching & finding topics
-
easily links to external reference material
|
Constant Fluctuation:
-
instant publishing, erratic version control
-
lacks formal approval and sign-off
-
presents a moving target for team
|
|
Security:
-
no documents floating around or mailed
-
uses domain security to access
-
group and user level access control
|
Not Very Portable:
-
not formatted for printing
-
makes milestone submissions difficult
-
not organized for reading end to end
|
Pro: Collaboration
Wiki supports multiple editors working simultaneously on
different topics. This appears to be the trend for all major undertakings. Take
a look at Google Docs for an extreme case, where multiple users can edit the
same spreadsheet at the same time.
Microsoft is working on a similar service
for Office, but its implementation is somewhat different. Currently, it's more common to navigate
to a Word document on the network, open it on your desktop, edit a paragraph,
and hit "save" -- only to be told that the file is locked by someone
else. That doesn't happen with Wiki unless users are editing the same exact
topic.
Con: Design Mayhem
Everyone has heard of
the adage and probably experienced it for themselves: "Too many cooks in
the kitchen spoil the broth." Clearly the biggest concern for most
designers new to Wiki is the lack of cohesiveness that comes from group design.
They have a reason to be concerned. I've seen Wikis that were completely
disorganized, disjointed and more or less unusable as a design specification as
the various editors war over its contents and presentation. Clearly not
everyone is a writer -- or particularly good designer. There's another adage at
play here: "Just because you can, doesn't mean you should."
In my experience, the
best design documents were written by designers adept at technical writing who listened
as well as they wrote. They were able to take the various contributions, notes,
and feedback from the team to create a cohesive, attainable game design
specification that represents the goals and ideas of the team. The role of lead
documenter just doesn't exist in Wiki. It runs counter to its philosophy.
There are a few ways
to avoid these problems without becoming a complete Wiki Nazi:
1.
Most Wikis can be configured to block anonymous
users from making changes.
2.
Some Wikis offer version control and change
history tied to user name, which offers some accountability and recourse should
there be some undesirable change.
3.
Additionally, most Wikis offer read-only
access control per page by group or user. This is less than ideal. I've only
ever used it to keep people from seeing embedded database passwords.
4.
Establish a style guide for each type of content
and create a framework to structure all the Wiki pages into categories.
5.
Enforce a formal migration of Wiki pages so that
proposed ideas, notes and specs under development are kept away from published
specifications.
6.
If there isn't a lead designer with time on his
hands to edit Wiki pages, have a designated WikiMaster at the company whose job it is to clean up and organize
Wiki pages.
Pro: Browser Friendly
Wiki works with any web browser. The URL uses the Wiki topic
name in simple CamelCase,
making finding pages very easy. All Wikis have some way to tag pages for
searches -- essentially applying key words to make associating and searching
for the topics very easy. Confluence calls them labels and TWiki calls
them tags.
Wiki pages
can also be grouped in parent-child relationships. It's fairly easy to make a
switchboard page with a navigation tree to each topic. Depending on the Wiki
solution you use, the navigation tree can be auto-generated.
Wiki makes it easy to have links to other Wiki pages,
attachments, downloads or external reference material. If you have a YouTube
video that's a great reference, you can embed it right on the page. You
wouldn't dream of doing that in Word Documents. Even though it's technically
possible, it doesn't print and it relies on an Internet connection that you
can't be sure the reader has. With Wiki, you can be sure embedded reference
material will display fine.
|
Printer-Friendly Version
I would recommend anyone to try one, even if it is a single component that must be documented.
As Roberto, I'm recommending everyone to try them.
As with all team-oriented product development efforts, in games or otherwise, a successful experience with something like WIKI comes down to personal preference giving way to the greater good of team preference . . . or leading the way with an approach enjoyed and appreciated by the team. Habits are hard to break and robots are hard to find. I have been looking for them for years. ;)
Excellent job of providing an in-depth big picture perspective on the pros and cons of utilizing WIKI products. Thanks, Tim.
I've always liked the idea of Wiki's and have consumed my fair share of them, but I wonder if google docs or Adobe buzzword wouldn't end up being better solutions. I wonder this because they don't strip away the word processing behaviors that we are all used to but add the collaboration, version tracking and rich layout capabilities that game design docs need. With these tools, you can still create your design doc in your favorite word processor and then upload them so that they can be collaborated on.
I'm not totally convinced that my suggestion would really work, but thought I should throw it out there. GoogleDocs was mentioned in this article - but I would recommend taking a look at Adobe's buzzword as well.
Thanks for this great article. You got me thinking...
I hope that as more people use Wiki for design and production in the game industry, more plugins, tools, and evolutions of Wiki will appear to meet our unique needs!
With the formatting, it's true that as long as you're not being ambitious, wiki markup is generally easier than HTML - on the other hand, tables can be fiendish, and a lot of the sorts of extensions you'll see in use on wikipedia (for example) aren't shipped by standard with mediawiki as far as I know (which then requires you to detangle a web of templates to work out how you can get a nice, red "this is deprecated" warning box).
If you want it saved out, there's a few programs out there that can download and package up websites for offline browsing.
You can't expect to put up a wiki and get benefits instantly and for free, someone needs to lead the way on encouraging people to use it in the right way, work out how to deal with access, best practices etc, setting up templates (or some form of reusable code), and that's going to absorb the time of someone who could be doing something else.
All this aside, I much prefer a wiki to a massive document, especially because we don't use it for doing a design doc, but documenting engine features and how to use them etc (which doesn't need central approval). The benefits scale a lot when you're working with large teams and remotely.
I believe Google Wave will spice things up, particularly from the open-source nature of the platform, you can tailor it to what your company needs, should you have someone to do so. For smaller companies, it would be a great way to work on ideas and documents (thanks to the ability to mark up and comment waves) without the need for a lot of meetings that may be inconvenient for folks who have to telecommute.
Best of all, no need to set up a Wiki server.
E.A.W.
Formatting requirements rank #2, and they mostly seem to be an artifact of old processes.
So far we are impressed. And for all the people stating that Wiki can become a mess and GDDs can't, you do know that you can allow only certain people to edit, right? If you want to, you can have your designer as the only editor, old-school style, but the ease of use and browser visualization, as well as version control, will make the documentation much more accessible for the rest of the team than a 300-page pdf tome.
Why not use best of both worlds? I mean, the Wiki offers multiple-user information editing while Word offers the speed and time-saving text editing tools. Those are the biggest differences, right? I think that organizing a Game Design document in Word simply by splitting it in documents by subject (like Wiki does) can greatly increase how many people can edit information, since that seems the major issue.
For instance, instead of having a document called Economy_System.doc, containing all the information about your economy system and filling 25 pages, you could have it split in several documents, like so: Player_Income, Player_Outcome.doc, NPC_Income.doc, NPC_Outcome.doc, and so on.
On another note, I do agree that the change log is not present in Word documents, and that could be a hassle to deal with. That's why having a rigorous notification process is needed so that information affecting other departments is sent out. For this there are various solutions, including simply having new/updated information highlighted within a document and leave it highlighted until some kind of "Newsletter" for the project is sent out with all the changes. This is tedious, I know, but I'm sure someone could come up with a better idea.
I think we just struggled with the "Con's" of the article ;) but still the one major advantage is, that all the information is accessible to everyone.
I frequently spend a few hours going through, reading new documentation and telling people what they need to improve upon, reclassifying pages and adding TODO category tags and notes.
You have to keep in mind when documenting, who you are documenting for, and how you're expecting them to find the information you're putting there. Unlinked pages are almost useless, as are uncategorized pages (search is ok, but shouldn't be the primary way of finding information, I keep the special pages for these two items on the front page of the wiki to remind people what they need to do). The front page should probably link to your top-level categories, and you should probably be able to learn about and find any page within 3 or so clicks of that page. I've seen programmers produce pages that would barely tell anyone how to use the functionality that they've created, what it's for (and not), and why it was done in the way that it was.
It's also worth remembering what a wiki is not for: it's not there to stop people from asking you questions. If that's the most efficient method for getting the information (and in small teams it probably is), you shouldn't fight that too hard. If you're not there, through vacation, office hours, moving on to another job or simply because you haven't looked at something in a long time and don't remember 100% yourself, the wiki is there.
I also harass new employees to point out pages that they feel are missing from the wiki documentation.
Wikis have an aura of "democracy" and "inclusiveness" about them. There is an assumption that any person reading a Wiki is authorized to make changes and that those changes are meaningful. However, software development is not a democracy; successful projects are a benevolent dictatorship. Giving people an Edit button on a design document can give the idea that anyone can change the design... hey, cool, a Wiki, I'm a designer now and can gainsay the designers when I disagree with my non-designer viewpoint. Ditto for implementation guides... hey, cool, a Wiki, I'm a coder now and can second-guess the coders with my took-a-class-in-PHP-once sensibilities. Marketing strategies... hey, cool, a Wiki, I'm a PR guy now and can pipe in with my engineering viewpoint because engineers make the best marketers. Legal documents... hey, cool, a Wiki, and I saw "Law and Order" last night and read a Gamasutra column :) And if you didn't want to be granting anybody the ability to change anything, why did you go with a Wiki?
I've run into the above before. Many times, actually. WikiPedia has been so successful at what it did that it's attached its philosophy not just to the project, but to the tools that made the project happen. And sometimes that philosophy is entirely inappropriate.
- can add anything that's missing, so long as they express their confidence level in the accuracy of what they're saying
- can clarify anything, so long as they are sure the clarification is correct
- should email questions and comments to the most likely person to know the answer, not put them in the Wiki.
However you still need a editor with time allocated (or a concerted effort from a number of people) to maintain usefulness of the structure, the accuracy of the links and any index pages.
If you can do this, using a Wiki is a very powerful process which can replace almost all other documentation apart from code comments and external docs.
Thus, I have a question: are there some wikis (or similar) regrouping all of wiki traditional features and word processinf format feature? (that means, no messing with tags)?
http://www.gamasutra.com/blogs/DanielHelbig/20090809/2707/Microsofts_Word__Lets_
bury_the_dead__20_Reasons_why_you_should_write_your_GDD_in_a_Wiki.php
Two wikis I'd recommend checking out are Deki http://developer.mindtouch.com/Deki and Trac http://trac.edgewall.org/ (which also has robust ticket tracking.) Both have good WYSIWYG editors, though Trac's is a non-core plugin and more basic.
So long as your wiki is internal to the studio everyone being able to edit is not a problem, just disallow anonymous edits (a housekeeping detail rather than a security measure) and trust their professionalism. I've never had a problem with bad edits other than the occasional prank on people's personal pages.
Most publishers require a design doc that you'll need to deliver in Word or PDF format, but careful use of transclusion and some Word macros can make generating a GDD from a wiki a fairly painless task.