How To Make Documents Work For Your Team
All video game production projects need documents, whether it’s a four page description for an iPhone game, Xbox Live Indie Game, Flash game or a 65-doc library for a AAA multi-million selling game on PS3, X360 and every other platform. On all video game development projects, similar problems come up: people don’t read documentation, people read documentation but find them confusing, documentation don’t get updated or the updates don’t get acted on. Fortunately, there are some ways you, as a game designer (or as whoever’s writing a doc) can help.
Make it readable
Documentation that isn’t read is worse than not having the documentation at all because (a) game designer time is wasted writing it and (b) the game design team assumes the other teams know what they’re doing, when they’re actually relying on other methods, like reading tea leaves. Game developers are busy people: it isn’t easy to convince us to read anything. But there are some ways you can help to make sure the team is reading what it needs to.
Make it approachable
That means no doc over 50 pages. If it’s over 50 pages, split it into a doc per section. Reasonable sized fonts. Diagrams instead of pages of text. A glossary, if you need one. Don’t make it any scarier to read than it has to be.
Make it navigable
Make a studio doc template and stick to it (within reason - a sports game and a beat ‘em up are going to need different documentation, but they’ll both need a UI section and there’s no reason that section shouldn’t always be at the end and always run in roughly the same order. Help the poor sound designer who’s just been shuffled onto his third project in six months: let them turn straight to a ‘Sound’ section with ‘UI Sounds’, ‘UI Music’, ‘In-Game Sound Effects’, ‘In-Game Music’ and so on all laid out as they’d expect. Nobody’s creativity’s being stifled by keeping the same structure (and of course the template can be tweaked and improved as time goes on) and just having that template there is a great way to avoid designers (and producers) overlooking things. It’s also a massive help to designers writing their first design doc to have a skeleton to fill in.
If you really do have to have a big doc and you want to make it quick to flick through, put a navigation bar at the bottom of the page, with the appropriate section highlighted to show where you are (this is a five minute job if you use Word’s section tools and put it in the footer). That way you can thumb through the doc flickbook style and stop when you see what you want. For extra points, make it actually operate like a navigation bar on a website and skip you to the start of each section if you click on it.
Exception: while it’s great to help teams find exactly what they’re looking for, be wary of people zeroing in on exactly what they think they need and skipping the vital stuff they thought didn’t apply to them. There’s nothing wrong with putting a big note on the second page for each team, calling out sections they might otherwise skip over (‘Weapons team: as well as the ‘Weapons’ section, make sure you read the ‘Animals’ section: the rhinos have their own built-in particle cannons’ AND put a note in the Weapons section itself linking to ‘Animals’. By doing this, you’re implicitly confirming that it’s okay not to read the whole doc, but that’s probably going to happen anyway: use your best judgment.
Now you’ve made it easy to pick up and start reading the doc: how do you make it *work*?
Avoid duplication
Never, ever, ever, state the same facts in two places. Every time you list, say, the weapons in the game in both the introduction AND the weapons section, that’s two places you have to keep it updated and twice the potential for outdated information. Cross-reference instead: use hyper-linking: it’s better to make people click a few times than have someone miss a vital widget because it was added in one section and not in another. Introductions and Executive Summaries (which producers always insist on) are a real pain for this: producers (and publishers) like nice, simpile lists and they don’t want to read further than page three, so they want to duplicate all the essential information here. Keep it short, and check it every time you update the doc.
State exclusions
You have to realise that people will use your doc in ways you never intended. For example, an artist will, when they’re in a hurry, look at a list of creatures in the game on page 42, see that there are five and schedule five artists to tackle one each. Only there aren’t five creatures: there are six. The list on page 42 was in the sound effects section, and you only listed the creatures that needed sound effects (giraffes are silent). This isn’t a joke. I’ve seen lists cut and pasted from a doc, passed through a chain of ten people and then relied on as gospel for a completely unrelated discipline. So don’t list the animals that have sound effects in the sound effects section. List all the animals, and say: ‘Giraffe: this animal has no sound effects’.
Remove ambiguity
It’s better to be clear. If in doubt, state it. Don’t write lazily. This is lazy:
All rhinos can be ridden by players of level 14 or above.
Hold up. Does that means that all rhinos are rideable, and all rhino riding requires players to be level 14 or above? Or does it mean that level 14 players have their choice of all rhinos in the game to ride, but level 13 players can ride some of them? Let’s try it again:
All rhinos in the game can be ridden. Riding a rhino requires the player to be at level 14 or above.
English
This leads on to English (or whatever language your dev team has agreed to work in). Designers (and other doc writers - don’t forget the Technical Design Doc author) aren’t necessarily great writers: in terms of technical English (spelling, grammar, punctuation) or writing clearly and in an easy-to-read style. And that’s not necessarily a problem: *except* when it comes to design documentation. Don’t get the wrong idea here: good writing skills don’t make someone a good designer, and I’d much rather a designer have fantastic ideas but be unable to express them than have no ideas but great communication skills. Most designers on a large team don’t have to write documentation. But for the ones who do have to, writing skills *are* important because for every word they write, potentially 60-100 people are going to read it. Luckily, writing skills are easy to assess and easy to learn. I give a basic English test (a five minute, half-a-side of A4, spot the mistakes thing) to every design candidate I interview. I don’t exclude candidates with poor English skills, but if they move towards a position where they’re going to need to do a lot of writing I do make sure they’re trained up and ready for it when they write their first GDD.
Understand the reader
You should be able to identify the common mistakes the rest of the team will make. Call them out, in big, friendly letters. If there are two terms that sound very similar and could cause real problems if they’re confused, say so. Better still, think up different terms. Be helpful: ‘Remember, we don’t need to do this on PS3 because we have blah’.
Updating
documentation need to be updated constantly, to keep them in line with the design, at least until you reach whatever your agreed ‘the design is now locked’ stage and start using change control. Call out changes so that people don’t have to read the doc itself, if you possibly can. Do a daily email collecting together any design changes (if you go days without needing to do one, so much the better). Every change gets a one line description, a link to the section of the doc where the changed section can be found, and - and this is crucial - a note as to whether that’s it, or whether there’s more detail in the doc. What you’re trying to avoid here is both people reading the doc when they don’t have to, and people not reading the doc when they need to because they’ve assumed they’ve already gleaned all they need to. Here’s what I mean:
UI: New PS3 hardware requirements - added ‘Move Disconnected’ message (link)
Sound Effects: New 3D ambient effects added - MORE DETAIL SEE (link)
Version Control
Keep documentation under version control and have a change control section at the start where you list everything that’s changed in the latest version. Yes, this will get long. If you’re doing the update email as described above, you can cut and paste the same text and control section into an email, save the doc and check in, send the email and everything’s done.
Reference
On some projects, there’s a huge amount of information that all members of the team might need access to, but that the design team isn’t creating (say, lists of tire pressures for 400 cars, or the complete flight manual for an Apache gunship). The worst case scenario is when some of the information is out on the internet and different team members are consulting different sources. Allocate one person to be the ‘project librarian’. When the team needs a fact, they’re responsible for ensuring it gets stored somewhere everyone can access it - saves time and mistakes, and if a mistake is made it can be corrected once on your Wiki or in your reference doc and the change can filter down to everyone.
