Gamasutra: The Art & Business of Making Gamesspacer
Learning the Ways of the Game Development Wiki
View All     RSS
August 29, 2014
arrowPress Releases
August 29, 2014
PR Newswire
View All





If you enjoy reading this site, you might also want to check out these UBM Tech sites:


 
Learning the Ways of the Game Development Wiki

July 30, 2009 Article Start Previous Page 2 of 4 Next
 

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.


Article Start Previous Page 2 of 4 Next

Related Jobs

Sucker Punch Productions
Sucker Punch Productions — Bellevue, Washington, United States
[08.28.14]

Lead Mission Designer
Sucker Punch Productions
Sucker Punch Productions — Bellevue, Washington, United States
[08.28.14]

Environment Art Lead
Digital Extremes
Digital Extremes — LONDON, Ontario, Canada
[08.28.14]

UI ARTIST/DESIGNER
HitPoint Inc.
HitPoint Inc. — Amherst, Massachusetts, United States
[08.28.14]

Senior Game Designer






Comments


Roberto Alfonso
profile image
At work we use TWiki. I hate it, but mostly because I am used at MediaWiki (where I acted as administrator). However, in all a wiki is useful when working with documentation, since it is very easy to write (you almost don't think in the tags as you would in HTML). Also, being able to go back to any past version and check differences is, in itself, a huge advantage.



I would recommend anyone to try one, even if it is a single component that must be documented.

Jesus Alonso Abad
profile image
My personal experience using wikis to document development is really positive. It offers not only a collaborative way to create documents, but new ways to organize information.



As Roberto, I'm recommending everyone to try them.

Eric Scharf
profile image
While I, too, am old school with my documentation methods, I can certainly see, through your article, and have experienced the benefits of utilizing a Confluence.



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.

Dan Thatcher
profile image
As I look at the pros and cons that have been presented, it seems that the suggested solutions to the cons are challenging to implement. In other words, it seems that the con solutions actually create more cons.



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

[User Banned]
profile image
This user violated Gamasutra’s Comment Guidelines and has been banned.

Renan Rennó
profile image
Maybe Google Wave will spice things up.

Christian Arca
profile image
I personally cannot deal with Wikis. We've tried using them at our studio and they result in a formatting mess. What we have resulted to doing though is using subversion for GDD document control. So as lead the edits are sent to me and I inspect the change log. If approved then the documents are committed if not then they go back to the designer who makes the appropriate changes. Sometimes it's a bit taxing but it's not all too bad.

Thomas OConnor
profile image
I've had success on two projects using Wiki as our production log. Our scrum meetings, backlogs, and burn charts are all updated on a Wiki (using MediaWiki), and so far everyone's had a pretty reasonable time with it. A bit cleaner than lots of post-it notes on the wall, but it does have it's hairy sides.



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!

Daniel Speed
profile image
We've used wikis for a while, and a bad one (or badly set up one) can really hurt you if it rapidly becomes slow and unusable and you can't find anything.



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.

Edward Williams
profile image
"Maybe Google Wave will spice things up. "



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.

Christian Arca
profile image
@Thomas - I'm going to take a look at MediaWiki. Unfortunately we were using our project tracking software for Wikis which had an intolerable system so anything and I mean anything worth document took at least 30 minutes to properly modify or add.

James Hofmann
profile image
I think the number one thing wikis need to work for project docs is automatic organization - for example, the category tags in MediaWiki. Without them information gets muddled because the pages for project documents won't naturally link to one another in the way that a Wikipedia article does. But once you can tag and group pages in different ways and auto-generate listings, it gets a lot easier to find what you need.



Formatting requirements rank #2, and they mostly seem to be an artifact of old processes.

Mark Venturelli
profile image
We have been using a Wiki tool for all our projects. I highly recommend everyone to try Zoho Wiki (http://wiki.zoho.com). It is free to use (with file size limit), you can organize the documentation easily in a parenting tree, make it private, allow only specific members to edit content, it has version control (including the most useful "ctrl+z"-style reversion) and you can configure it to email you every day with a list of changes made by your users, divided by section and date.



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.

Julien Tremblay
profile image
Having worked with both Word documents and Twiki, I can personally say that I prefer Twiki way over the Word method, simply because we could have multiple members could browse / edit information rapidly. But quite frankly, the cons of the information mess and structure from a Wiki is generally way too chaotic and results in more harm done than good.



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.

Neil Gower
profile image
I'll chip in that in a top-down style of organization, a wiki is not a good fit. Wikis work in collaborative environments where anyone can contribute to anything if they see the need. These are very different ways of working, and the culture clash is much harder to overcome than the install process of any wiki software. Before choosing a wiki, you need to know what style of team are you building.

Philipp Horwath
profile image
We (10 students) used the wiki environment at our university for the game development. In the beginning it worked just fine, but the problem was we didn't had a real project manager (or nobody of the students cared :) ). The result was that information was edited somewhere and data occurred twice. Also the problem was that people asked the information, before looking it up



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.

Daniel Speed
profile image
You very much get out of a wiki what you put into it - I'll reiterate that you cannot simply put one up and only expect good things for no effort. What you get is increasing payback over time, for diminishing effort (there's more existing documentation, standards, people are more familiar with editing and writing it...).



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.

Lance Rund
profile image
As has been alluded to previously, with a Wiki there is an intersection of several influences which are counter to each other. Some are obvious (the presence of an Edit button on the screen does not magically confer the viewer with the ability to write coherently), others less so. One which I've run into is particularly insidious, though. It's political.



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.

Jonathan Lawn
profile image
My experience is that it is fairly easy to set a culture so that everyone



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

Andrea Di Stefano
profile image
I had a terrible experience on a student project using a wiki, mainly due to the effort required by text formatting. While most wiki functions are great (we used DokuWiki), in the end we reverted back to more conventional word processing tools, much easier to edit.



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

Daniel Helbig
profile image
Hi, I wrote a blog post about the reasons I believe a Wiki makes more sense for a GDD. I would highly appreciate it if you could tell me your opinion about it.



http://www.gamasutra.com/blogs/DanielHelbig/20090809/2707/Microso
fts_Word__Lets_bury_the_dead__20_Reasons_why_you_should_write_you
r_GDD_in_a_Wiki.php

James Everett
profile image
Back at GDC 2008 I did a poster session on 10 Tips for a Successful Wiki (text here http://www.brainofjames.com/?p=62 ) and have become a big fan for documenting projects.



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.

Loic Kohler
profile image
I guess now I have something to conduct some research on in the future of gaming and programming uh!. But I must say this was a nice read and I find that this was very useful.


none
 
Comment: