Author: by Tim Ryan

[Game design veteran Ryan -- most recently a designer on Fracture -- looks at the Wiki as a game design and development tool, asking -- is it the right tool to use to document game creation, and what are the pros and cons of using it to store design information about larger-scale games?]

Introduction

As a self-described old-school developer, I have written or directed the creation of game design documentation since the early '90s, but recently I had the opportunity to work with teams using internal Wiki websites to document their game design specifications. I wasn't sold at first, given the discipline that goes into creating clear, precise documentation, but I saw a lot of positive aspects to the approach.

I did some asking around, and I found that quite a few people have worked at companies that used Wikis. The vast majority were making self-published games where the demand for documentation milestone deliverables to a publisher didn't force a printed format onto the team.

I realized that Wiki is probably something that's here to stay and I'd better learn to adapt. So I did a little bit of research and found the pros and cons of using Wiki for game design documentation and some methods for overcoming the cons. This article seeks to share what I learned.

What is Wiki?

Wiki was invented by Ward Cunningham in 1994 as a way for programmers at his company to share ideas. It is a simplified markup language loosely modeled after Apple's Hypercard -- which, interestingly enough, is credited as the forefather of HTML, the standard Web Browser markup language. The difference with Wiki is that it is much simpler and hasn't spun out of control in complexity like HTML has over the years. Anyone can edit it, which is the point. It's not an information presentation language: it's an information sharing language. It promotes communication and group contribution through ease of access.

Over the years, Wiki has spread to other companies and to public websites. The most famous is the online encyclopedia Wikipedia, written entirely by individual contributors around the world. The prominence of Wikipedia as a respected repository of information is the ultimate proof of the success of Wiki's goals. Thank you, Ward.

Is Wiki Right for Game Development?

Wiki was originally designed for use in a software development company before being adapted for community and commercial sites. From what I could gather, a few game companies have used it for quite a long time. The fact that more and more video game development companies are starting to use it should be no surprise. It's caught on.

Our industry has grown. The size of the projects, the depth in the games, and the sheer amount of information is staggering. There is just too much for a single designer or producer to write up. There is also just too much information for a single design document, even if it were divided up into sections. Wiki solves this issue because it allows many individual contributors and a browser interface to organize and find information.

Perhaps this is just a side-effect of being gamers or an influence from the MySpace, Blogger, and Twitter culture, but game developers seem to have a small attention span and appreciate the bite-size pieces of design that Wiki encourages. They don't like wading through 100 page design specifications. Each Wiki page is a topic, and it can easily be linked to other topics, be grouped into sections and be labeled for searching. In short, Wiki makes design more accessible.

Why not use Sharepoint?

The answers are simple:

1. Sharepoint isn't cheap. Many Wiki solutions are free or fairly inexpensive.

2. Sharepoint is cumbersome and is more of document hosting solution than a website. I've literally waited minutes for a document to transfer off the site and be loaded by my MS Office application rather than come up in my web browser as a web page like Wiki does.

3. A tool that's used is more useful than a tool that's not. In my experience, Wiki is more readily used by the team members. It gets more contributors and more readers alike.

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

Con: Constant Fluctuation

The same factors that make Wiki powerful -- speed of change and accessibility, lend itself to constant fluctuations of the design.

This can create a moving target for the team, make formal review and sign-off difficult, and put in doubt the entire validity of the design. There are a few ways to combat this:

1. Most Wikis offer a way to show recently changed pages. At a minimum, one can monitor this list to see what's changed, but it necessitates a vigilant viewer and it doesn't differentiate between major and minor changes.

2. Some Wiki's offer notification options when posting an edit. Editors can include a comment and quantify the significance of the change. Notifications are sent via E-mail to users who have signed up to watch the topic.

3. There are a number of plug-ins for handling approval of changes. Certain users or groups are considers approvers and some of the advanced plug-ins have a customizable approval-flow process. Changes to pages trigger the approval process to start over for that page.

4. You can create a Wiki page that displays links only to the pages tagged with certain labels, say "Feature_Change". From that point on, any page labeled with "Feature_Change" will show up as a link on the Wiki page. See the examples below:

5. What's missing in Wiki is MS Word's ability to track changes and associate comments by line. Certainly, you can add color-coded comments and put colored panels around the section that changed, but then your Wiki pages would start looking like a coloring book and your comments would be exported with rest of the Wiki text. They wouldn't disappear like they do in MS Word when you change your view or print options.

I solved this recently by combining a Java plug-in called Composition and combined its cloaking ability to hide sections of text using a graphical toggle button with a "no-export" java macro that a friendly user had posted on the internet.

I replaced the graphics with something that looks like a sticky note line marker, and presto -- you get sticky notes that mark a specific line or block on a table, and you click on it to read the comments. The hidden text remains searchable, so you can put any key phrase you like inside and it will show up on the search.

Pro: Security

Wiki can be hosted public facing or privately, using your company's domain security. For private wikis, users have to be logged in to the domain to see anything. If that's not enough, some Wikis offer group and user account security that will provide full access or read-only access for registered users.

Access may even be tuned to certain name spaces or specific branches of the Wiki. I would recommend doing both; domain access is often granted to visitors or remote users who you don't necessarily want browsing your confidential designs.

Wiki can and should be backed up for further protection. Depending on your solution, wiki data is either stored as simple text files or in database. Be sure to tell your system administrator to back it up. Databases can screw up, users can mess up, and trolls can trip up your Wiki. A physical backup on a tape or DVD can be a life saver.

Con: Not Very Portable

As mentioned, Wiki is not formatted for printing and cannot be e-mailed, zipped up or otherwise transferred like a Word document. However, most advanced Wikis provide some options to solve this. Even if yours doesn't, there are many off-the-shelf solutions or plug-ins that help resolve this issue.

1. VPN access is a viable solution for some companies if they trust both the outside person and their team to not break anything.

2. Some Wikis have an option to save as HTML, essentially creating portable website that you can zip up and FTP or e-mail away. While it's not formatted for printing, it is now electronically transportable.

3. Both Confluence and TWiki offer PDF export options. While both can be distributed electronically with functioning links like HTML, the PDF also is formatted with page breaks, table of contents, etc. so it can be printed. It will NEVER be perfect, but it does present a viable option for a developer to overnight a printed design spec to their publisher.

Just be sure that graphics fit onto a page and that tables can be squished down to letter-sized portrait printing, as landscape printing particular pages is not an option (as least not that I could find).

4. Whatever export method you use, you should always organize Wiki branches as you would expect them to be read. Take a cue from standard design documentation and create sections with summary pages and links to the child pages within the section. Also, police your Wiki so that new topics are properly filed into the correct section.

Conclusion

At first glance, I found Wiki overwhelming. The sheer number of pages and contributors made it appear like a contributor to chaos rather than a beacon of information. I really missed my docs. At first I would produce everything in a standard doc form, then export it to Wiki, but that wasn't using Wiki for its intended purpose.

Eventually I saw the light, and I worked around the negatives of Wiki. This old dog learned new tricks. Even now as I introduce new hires to Wiki, I can see in them the same confusion and concern that gripped me.

But after the orientation, they come to appreciate the accessibility and team-oriented nature of Wiki. It's this team-oriented nature of Wiki that sets the foundation for projects to promote team-contribution and consensus. I wouldn't dream of doing another large project without it.

My exposure was limited to TWiki and Confluence, but there are many more versions out there. I am sure many of the readers have encountered Wiki before, so I invite people to share their experiences and what form of Wiki they used.