I searched these forums to see if anyone else had done something like this before, but couldn't find anything. Anyway, in the last ten days or so my team and I have been putting together a wiki with all the development information related to our game. We just made the wiki public tonight, and although it's still a work in progress and not fully complete, you can find it at: http://allacrost.sourceforge.net/wiki Information we put in this wiki include:

• Our current short-term and long-term team goals, and what we have to finish to achieve them.
• A record of all the positions we are currently trying to fill, and where we have posted recruitment/help wanted threads.
• A list of all the highest-priority artwork, music, and code that needs to be done for us to meet our current goals.
• Documents explaining the standards of how to create artwork, music, and code for the game.
• A number of pages documenting the code that runs the game engine.

And several other pages related to the development of our game, such as what software we've used and a list of people who have come and contributed. Has anyone tried this or seen something similar attempted before? Do you think a development/content wiki can help a team to stay more organized and focused on the tasks that they should be achieving? Is this a good idea, a bad idea, or do you think it won't make much of a difference? I'm just curious what people's initial reaction to this type of content management is. So far I'd say that it's working out great for my team, and especially for me. Before we had all of our content/documentation/standards tossed around across different threads in our forums and things were generally a mess. At the very least, I think it will help provide a more "insider" perspective for hopeful new game designers. They can see a real example of the design decisions made in producing a game, and in many places read why those design decisions were made. Thanks in advance for any C/C you can give into this idea, whether it be good or bad. [wink]

One game with an official wiki that comes to mind is Bzflag.

Well yes, I know that Battle for Wesnoth has its own wiki as well. But both BZFlag and Wesnoth's wikis seem to serve a different purpose than what I'm talking about here. As far as I can tell, neither wiki accurately describes how the game works, for instance. It's more of a wiki for people who wish to add content (maps, campaigns, etc.) into the game, rather than a wiki recording the procedures for development of the game.


Do you see what I mean, or am I totally missing the point here?

Quote:

Original post by Roots Well yes, I know that Battle for Wesnoth has its own wiki as well. But both BZFlag and Wesnoth's wikis seem to serve a different purpose than what I'm talking about here. As far as I can tell, neither wiki accurately describes how the game works, for instance. It's more of a wiki for people who wish to add content (maps, campaigns, etc.) into the game, rather than a wiki recording the procedures for development of the game. Do you see what I mean, or am I totally missing the point here?

Well, the BZFlag wiki has a Developer section which has some on how it works. It doesn't appear to have as much developer information as your wiki though. Anyway, it does sound like a good idea. Actually, for my next large, multiple developer project I was thinking about having a wiki.

Quote:

Original post by Roboguy Well, the BZFlag wiki has a Developer section which has some on how it works. It doesn't appear to have as much developer information as your wiki though. Anyway, it does sound like a good idea. Actually, for my next large, multiple developer project I was thinking about having a wiki.

I highly recommend it. It makes my job as a project leader so much easier, because I'm not the only one with access to modifying this kind of information, so it's much easier to keep things updated. Even if you were to grant your entire development staff access to modify sections of your site, it's just not as easy to edit and re-publish a website as it is a wiki. [smile]

The use of wiki and similar web-based tools for design and planning has become pretty widespread in commercial industry game teams. We're currently in the early phases of deploying a design/planning infrastructure at Egosoft, and the wiki concept is definitely high on the list. We're also looking at doing automated feature tracking, bug tracking, etc. through a unified system, so there's a lot more than can be done than with just a pure wiki engine, but the highly accessible and easy-change nature of wiki is definitely something we're aiming to recreate.

We've used similar web-oriented tools before, but the main problem (that we've had) is that discussion tends to decay into Thread Mode very quickly, and instead of work getting done, everyone just sits around and quibbles over some design concept. Haven't yet figured out what to do about that, and it probably won't be an issue for most teams were discussion access is tightly moderated, but it's something to look out for.

IMHO the most important part of a system like this is history. There are innumerable times during a game's production where you absolutely have to know what the official decision on Issue X was, and why that was decided. I'd definitely recommend structuring the system (and your rules for accessing the system) in a way that mandates the preservation of clear historical data. Even things that seem totally trivial and meaningless shouldn't be thrown out, because chances are someone will come back to that thing in six months and need to figure out if the behavior is intentional or a bug.

One final thought on code documentation: personally, I'm not a big fan of systems where code and the documentation are separated. It may seem reasonable at first, but in my experience, the separation inevitably leads to either the code or the documentation being totally out of sync with reality. Enforcing documentation updates every time the code is tweaked can be difficult and impractical, so I personally favor a much tighter coupling between code and documentation (i.e. keep them both in the same files as much as possible). The important documentation is how the code should operate on a game design level, not a code architectural level; ideally these two areas should be kept separate, so to document the intended game design in the wiki and the intended use of FoobarClass in the code itself is a great arrangement. Just my personal preferences, though.

Quote:

Original post by ApochPiQ IMHO the most important part of a system like this is history. There are innumerable times during a game's production where you absolutely have to know what the official decision on Issue X was, and why that was decided.

I completely know what you mean. This has happened to us a couple times before. Up until this wiki solution, 99% of our design discussion took place on our forums, which have their pros and cons. So the design decisions were all there in the forums somewhere, but it was usually spread across multiple posts or even multiple threads, so it was hard to piece the idea and decisions back together.

Quote:

Original post by ApochPiQ One final thought on code documentation: personally, I'm not a big fan of systems where code and the documentation are separated. It may seem reasonable at first, but in my experience, the separation inevitably leads to either the code or the documentation being totally out of sync with reality. Enforcing documentation updates every time the code is tweaked can be difficult and impractical, so I personally favor a much tighter coupling between code and documentation (i.e. keep them both in the same files as much as possible). The important documentation is how the code should operate on a game design level, not a code architectural level; ideally these two areas should be kept separate, so to document the intended game design in the wiki and the intended use of FoobarClass in the code itself is a great arrangement. Just my personal preferences, though.

Well in addition to our hand-written documentation, we do comment our code rather completely and use doxygen to generate technical reference documentation. But I find it much easier to answer the question "okay, how does this whole map mode code work?" when I don't have to skip around inside the code, reading comments, and jumping from function to function.


Our hand-written documentation is more of a general "these are the design concepts and how they work together", rather than trying to go deep into the technical level of the code. So even if the code undergoes several changes, unless the entire design is re-done, there should be little, if any, need to update the seperate documentation.


I see your point though, but I hope you see mine as well. I only treat code comments as pieces of advice on how to use certain classes/functions/structures and what a small snippet of code is doing, rather than trying to use comments to say something grandiouse such as "this is how the audio engine works from head to toe". [smile]

Oh, I absolutely understand - coming back to old code and trying to figure out how to work with it can be a very significant challenge. In that situation a high-level overview of the design rationale can be invaluable. I just tend to like to write that kind of material directly into the modules/headers where possible; this is so that the information is always kept right there with the code (and is thus less likely to become lost, especially if code is reused across projects) and so that the tendency to "forget" to update documentation is minimized, since you have to stare at the high-level docs when you go to tweak the code. I'm also lazy, and having documentation right in the code saves me from opening programs outside my IDE to figure out what I'm doing [wink]

I've found the best solution for this is to use a standard, commonly-agreed methodology for building the game code, and keep high-level documentation in whatever form your methodology suggests until a module/segment is finished. Once an area of code is more or less frozen, high-level documentation can be baked into the code in the form of header comments. Since the code is not likely to change much, the risk of the documentation falling out of sync with reality is minimal. Sometimes, that point is only reached after shipping the code - but that's fine.

Yes, managing all the information about a game online is a great idea. Wikis are one way of doing that. Just make sure you run through all the pages and cull out (or update) old, outdated information every once in a while.