Documenting a game’s design is a challenging process. During my time with BioWare many approaches were attempted but a standardized process was never found that worked for all projects, all the time (though this may have had more to do with various projects being unable to fit new documentation schemes into their stage of development than any flaw in the documentation attempts).
This section will summarize what worked a bit and why and why no documentation attempt ever really succeeded completely.
The documentation system I most prefer is using a wiki. With a wiki all team members can easily access up to date and relevant information.
- Linking Pages can be linked to one another so a system (say combat death blows) could be linked to the Animation system pages, the Combat system pages, and the Marketing department pages.
- One Version to Rule Them All Through the miracles of transcluding (if you don’t know this is a feature in wikis where a document section can exist in one place but be mirrored to many other places… changes to it are instantly reflected at all locations where it was mirrored).
- Strong Search The search feature of wikis is very valuable, easily allowing the reader to look up terms across the entire system documentation. This is also a drawback since many users don’t know how to make the most out of search systems… and many wiki writers don’t take that into consideration (i.e, they do not link to a subsystem because they assume readers will just search for it).
By flat documents I imply Microsoft Word or some other process that contains all the design documentation about an individual system/plot/level in one file. This file can be printed, e-mailed, posted and so on — that is multiple versions of it can be live simultaneously.
Flat documents have two major advantages:
- Ease of Use Everyone knows how to use Word or similar programs. There is no barrier to entry in regards to creating documentation.
- Easy to Read When the entire depth of knowledge about a system is contained in one well thought out document it is like reading a story — with a beginning, a middle, and an end. If done properly the structure of the written document itself stays with the reader. This is harder to achieve in a wiki where, in my experience, content is usually added quickly and without the polish that a flat document can have.
Both systems — wikis or flat documents — will get out of date.
The only way I found to address this flaw was to assign a single person as the librarian for all the documentation. It fell to this person to be responsible for perusing all meeting minutes that happened, project-wide, and making sure no contradictions between existing documents and meetings minutes appeared. If there are contradictions the librarian would seek out the truth.
Obviously it is expensive to have a dedicated librarian and the ideal person in this role has to know a little bit about everything (senior designers on the project make good librarian candidates, they are also in short supply on most projects). But if you want your documentation to stay relevant you really do need a librarian. Once team members start realizing that documentation has become out of date, they stop referring to it. That can cause problems.
I think a close to ideal solution that I attempted to mimic but never quite succeeded at achieving would be to use a wiki but have a very easy method to export sections of the wiki as word documents or other ‘flat and sealed’ types of documents that could be sent off.
Whichever solution is used you should embrace the concept of life stages (or approval stages) for documents. It should be clear to readers whether they are reading a document about a system being prototyped, a system being approved for development, or the final documentation for a system that can be given to whomever is writing the end user manual.
The Duh Factor
Here are some additional things:
- Trained Write Documentation writers need to have training on how to write good documents. This takes time and requires expertise. Don’t assume anyone can just sit down and write out documentation that will make sense to someone else later.
- Templates Create templates no matter what system you use, with proper headings, color coding for examples and so on. The more all your documents look the same the easier they are for team members to learn how to read.
- Time Spent The team needs time to read the documents! Seriously, this is important.
- Use me like this Be clear with each document or section who can use it and for what. If you describe super secret plot stuff label it as Not Fit For Marketing, if you don’t want them using it. You may just want to use a simple system on each section/document like ‘Approved For External Release’ or ‘Not Approved’.
- Don’t write just cause you cannot do other work If you are in the middle of prototyping and still don’t understand your gameplay systems it is a waste of resources to start planning dependent systems and gameplay. Don’t write your story if you are not sure how the dialog system will work. Don’t plan three hundred levels when you don’t know how levels are built. Sure the documents are cheaper to create than the final content but work wasted is still work wasted. Make sure your game has passed the ‘proof of gameplay’ test before going nuts on writing documents.
- “Everyone” does not and does mean everyone When you try standardizing documentation you need to decide what works best with a very small group of people. Don’t involve the entire company, you will never make a decision. Create something that works well and push it to the rest of the company once you are happy with the process. Then make sure everyone adopts it — marketing, admin, et cetera. The more acceptance you create the longer lived your standard will be.
Later I’ll have more specific examples of what I consider reasonable documentation.