Quick, Write This Down!
I’ve been reading a lot of it lately, so documentation is on my mind.
I don’t think anyone would argue it’s worthless in a project, but it begs the question - as I’ve worked on projects that both hardly have any and others that are immersed in it - how MUCH documentation is appropriate? How do we even determine this?
Of course, there’s the “no duh” things like scale and type of game. You nail down the obvious ones - Characters for an RPG, Weapons for an FPS, things like that. But at what point do you cross the line from Too Little to Too Much, when even just maintaining the things becomes a chore? In the beginning, they’re everyone’s friend - but near the end of the project, they seem to most often get discarded. How do you most decide what you need, what works for updating it, WHO updates it, and how to keep the evolution of the doc up to date so it’s consistently helpful?
I know this is case-by-case to the point where some might even think the discussion of such is kind of moot - but things don’t seem to improve on a case-by-case unless at least SOME attempt is made to look at them in a larger scale (at least in my view). So.
I’m going to make the key assumption here that there is an easily-accessible location for all the documentation that extends BEYOND a simple shared drive, or perhaps even a source-control solution like Perforce, AlienBrain, SourceSafe, etc. I’ve had personal experience with SharePoint, and although it is not my favorite tool ever, I can understand its utility, and have to admit it’s helpful to see it marked when a new document has been added, and when an existing one has been changed (and by whom). I believe SharePoint even allows you to tag certain documents to have an email auto-sent to you when they’ve been updated, which is helpful (in certain situations - I’d say when it’s an important doc that either everyone has access to but only a few can edit, or something only a few people can access and their changes are super-important). Obviously if a team is not communicating in person, there’s not all that much documenation can do.
So - what CAN it do, beyond a preproduction standpoint? Obviously it can help newcomers to the team get oriented and management see where things are going, but I’d argue as well that documentation - stuff outside the specifics of department, “translated” for everyone to read - is beneficial. I can’t understand the specifics of programmerspeak (although I should always strive to try), but having documentation that combines intent with a projected direction is valuable, and should always be valuable.
That said, as much as I like to document things “just in case,” I’ve also run into situations where files can pile up into a mess. I’ve been in attempts to collate disparate docs into a single file (which has led to its own share of complications, I tell you what)… and though I suppose perhaps doing something like collecting major elements together into a Master “Story Doc” (for example) might not be a bad idea, it also comes with its share of issues. If you’re on a Source Control System (and YOU SHOULD BE) only one person can tackle changes at a time - and if it includes a lot of systems that are still in flux, that could be problematic. Second, there’s the basic fact of human nature that most of us don’t like reading long documents. If I just want a basic character overview (that’s say, 5 pages), but it’s in a 40+ page Story doc, I might balk at such. Clear formatting and Ctrl-Click to Follow options in a Table of Contents should be involved, but those seem more like a stopgap and should be secondary to collating things at an appropriate time.
[Crap. I think my brain ran out of juice. Going to get some more caffiene, pick up rant again later. In the meantime, you gab about what docs you feel are the most important for different genres, what you’d imagine should stand alone always vs. get folded together, when and why. Probably only interesting to me, but what the hell :)]
Tags: game design