Tips on Writing Design Docs  

Posted by Raphael

I get a lot of emails asking about how to write design documents, so I thought I'd write up some short bullets here to cover the questions that seem to come up most regularly. Hopefully they are helpful, and if you have specific questions that aren't covered here, please don't hesitate to ask!


I've written a fair few design docs, and have had to decipher many more, so although there are people out there much more qualified to provide direction, I have some ideas based on my own experience -- take them if they're useful, ignore them if they're not.


Tips for Writing Design Docs

It's become common wisdom over the past several years that writing monolithic game design docs is really a thing of the past. With projects being as vast and complex as they are today, and teams being as large and as multi-disciplinary as they are, the notion that an individual, or a small group of people, can design an entire game on paper and have that documentation be relevant is...kind of silly.

But, equally silly is the notion that design docs are a complete waste of time and have no place in today's modern development environment. Documentation is very useful, very important, and if nothing else a critical part of the concept development process.

That said, there are probably a few 'best practices' that, if kept in mind, will help you ensure your documentation is of the useful variety.


Tips for Writing Design Docs
  1. Keep them short and sweet, but without sacrificing necessary detail. Being succinct isn't useful if the reader doesn't find the information they're looking for. So, focus on being thorough but avoid unnecessary detail.
  2. Focus on function. If you're a designer, it's probably not your job to go into incredible detail about how a particular UI element should look, or what an audio cue should sound like. You need to identify the function of the feature and describe what it does and how you as a designer need to be able to use it, including what elements of 'tunability' are inherent in the feature. Then, you let the experts in other fields weigh in on the supporting elements that help manifest the design feature into content the player experiences in the game.
  3. Rely on formatting. Proper formatting can do wonders to help communicate important elements of your design. Don't be afraid to use the *full range* of text formatting tools available to you in any decent word processor or online documentation tool (wiki, Basecamp, etc.). Yes, that includes indentation, colour, and even underlining! Don't be shy about using tables or charts, add imagery if it helps. Once you've written and iterated on several designs, in collaboration with the people who will work with you to implement the systems, you'll have a good idea of the type of information people need, and the best way to present it. Build a template and use it consistently, incorporating the best elements of other people's design documents into it, until you have a robust template that your entire design team can use. Consistency in documentation is of paramount importance, especially when you have many design clients and they need to be able to find information quickly, which leads us to...
  4. Know your audience. Are you writing your doc (I prefer to call them 'specs' myself, since they are meant to be the design specifications of a feature, not a document per se) for other designers? For your design lead? For an artist? A programmer? Internal stakeholders or external publisher people? All of the above? You need to know your audience in order for your documents to be effective. Write in clear language using common terms, and if you introduce new terminology remember to note the terms in a glossary, and make sure you use them consistently (and that other people use them consistently as well -- I can't tell you how many cycles I've burned trying to sort out confusion over inconsistent use of terminology...it's the enemy of clear decision-making!).
  5. State the intent. State the intent of your design right away. It gives immediate context, helps calibrate the reader, and puts them in the proper frame of mind to internalize the information you're about to deliver to them in the rest of your spec. Stating the intent first is also a very good way to find out if you're really ready to write your spec; if you can't outline the intent of the system you are documenting in a few short, concise sentences using clear language, then you may not actually be ready to write about it. Take the time to understand it fully in your mind before you go too far in your documentation. It's a common fallacy that writing design docs is the same as designing features. Do your design work up front, and use the documentation process to make sure your ideas are as bulletproof as possible.
  6. Layer your information. If some perpetually harried lead only has a few minutes to review your design, what do they need to understand and retain about it after they've moved on to the next thing? Present your information in layers, beginning with the basic foundational knowledge that is critical to understanding the spec, and add increasing layers of detail as you progress. It's a common documentation 'truth' that you should never use a new word or mention a new concept before you've had an opportunity to introduce it to your reader properly, so be organized about how you present your information so that you've built up the conceptual framework before you expect people to start building on top of it.
  7. Remember that information is personal. Or at least, the way we present it is. I'm a huge believer in the value of using white-boards and/or mindmapping software to brainstorm ideas (not just for design, but for story developing, and even project planning), but you need to remember that 100 people using mindmaps to design the same feature will come up with 100 different mindmaps that really only make sense to them. The information came out of your mind, wholesale and unfiltered. It's not supposed to make sense to anyone but you! So don't expect you'll be able to simply pass it on to someone else and they'll immediately grok the brilliance of your system. For me, mindmappers and whiteboards are simply a tool -- a hugely indispensable tool -- but a tool just the same. The map is not the territory, so try to remember that. If you can take the results of your mindmapping adventures and translate them into coherent documentation that follows some established 'best practices' (as they exist for your studio or team) and even use documentation templates, then you're way ahead of the game.

Well, that's all I can think of for the moment. If any other useful tips or 'best practices' come to mind, I'll be sure to update this post. In the mean time, feel free to shout out if you found this useful, and request any clarifications or updates you'd find helpful.

Stalker (Film); Metro 2033  

Posted by Raphael

Been super busy lately but sadly nothing I can really talk about, which sucks.


One recent highlight was that I *finally* managed to get my hands on a copy of Andrei Tarkovsky's film 'Stalker', the adaptation of the Strugatsky brothers' novel 'Roadside Picnic'. It is a truly fascinating, unusual film that I'm pretty sure deserves multiple viewings. It's an extremely minimalist film by today's standards, and yet manages to capture this wonderfully simple surrealism and a sense of beautiful abandonment in its settings. It's definitely not an action film by any stretch, so those of you who love the game (which is very loosely based on this film and the novels) may be disappointed to discover that the film and game have very little in common. The notion of throwing bolts ahead of yourself to expose dangerous hidden anomalies is a part of the film, but frankly very little happens that isn't almost entirely in the characters' (or the viewer's) minds. A very slow-paced film that is really quite perplexing. I recommend it highly, if for no other reason than to say you've seen it!

***

In another note, many of you have already clued in to the existence of a new 'Stalker-like' FPS called 'Metro 2033', which looks to deliver a lot of the atmosphere of the original Stalker game but with more advanced visuals and, if the trailers are to be believed, in a much more polished package. And, the game is set to be released on PC *and* the 360, so console players will finally get a chance to experience the Wasteland/Fallout experience as seen through Russian eyes. Metro 2033 is, apparently, also based on a novel, but not one I've ever encountered. In any case, the game looks very promising, and I find the premise really grabs you immediately.

This is one thing I always found lacking in the original Stalker, and it's something that the developers at GSC just don't seem to have clued in to (or else, they are intentionally hanging on to a style of presentation that is overtly clunky in nature) -- the studio just doesn't seem to have a very refined sense of how to present content to players. It's not that your game can't be noodly and complex and deep in its mechanics, but it doesn't also have to be clunky in UI, controls, and presentation of story and quest elements. But even looking at the latest trailers for the new Stalker game coming to NA in Q1 2010 (and already available in Russia and parts of Europe), it seems the developer hasn't really refined many of these elements.

In any case, I'm really looking forward to seeing more of Metro 2033 and I applaud THQ for having the balls to publish something one tick off the mainstream dial.


Breaking Story & Fringe  

Posted by Raphael

Time flies. It's been a little while since I posted -- apologies for that. Been super busy at work lately. I recently finished a really intense story-breaking phase, the end result being a complete throughline treatment of our game story. It's about the sixth or seventh iteration on the current game story, but the first version that I feel flows like a complete story. It's not perfect, but even getting here feels like a huge triumph.


Now we'll go through the inevitable process whereby everything gets broken into a million pieces again and hopefully it can be put back together in a coherent fashion. I have a huge amount of respect for writers who can go through this process and emerge with their ego and passion intact. I can see why for some writers who've been working in the industry for a long time, they switch into a kind of service-oriented mode where they abdicate any sense of real ownership over the work and take a very 'work-for-hire' type view on things. It's extremely challenging -- mentally, physically, and emotionally -- to invest the massive amount of passion and brainpower into trying to create something of truly lasting value (and hopefully of excellent craft), and then be able to switch it off and release it into the meatgrinder of the feedback and iteration machine, and twist and tear it out of shape to meet all the various requirements of seemingly endless lines of internal and external stakeholders.

But hey...that's the deal. Nobody said it was easy. :)

* * *

As a total aside, I'm happy Fringe is back on TV. It's not as good as X-Files was, but it's picking up steam and they seem to be trying to address some of the failings of the last season. They've removed that completely annoying idiotic external FBI overseer who was a constant pain in the ass and extremely unlikeable. They've started to focus on making Peter a more prominent part of the story, and develop his link to Anna a bit more strongly. I'm not sure I buy into the whole 'alternate universe' concept but hey, you know it's J.J. Abrams so it's gotta have some kind of weird hook and I guess this is it for Fringe. At least it's not time travel (tsk, tsk).

Interview with Narrative Designer's Network  

Posted by Raphael

Cool! I just did an interview with Stephen at the Narrative Designer's Network. The NDN is a new site dedicated to the art and craft of narrative design, and is meant to be a content and community hub for people dedicated to the work.


In the interview, I give my perspective on what narrative design is, what some of the day-to-day work is like, and some ideas of what the future might hold for the discipline. Check it out and post your feedback, either here or on the NDN.

District 9  

Posted by Raphael

WARNING: PLOT SPOILERS!

I'm always late to the party, but yeah, I finally managed to get to seeing District 9. It came very highly recommended by multiple friends and work colleagues and so understandably I went into it with very high expectations, which for the most part were not really met.

I think it was an entirely competent film, and went a long way towards satisfying several great geek sci-fi fantasies, but other than the unconventional setting, I found the movie to be overly predictable. The plot followed the expected beats pretty much to the letter, and there really wasn't much of a twist per se, so the whole thing -- while very competent as a production -- didn't come across as particularly inspired in terms of a piece of storytelling.

I may have missed something, but I'm not really sure how we're to believe that the aliens, who produce weaponry in such quantities that they use it as currency to trade for food, and whose weaponry is clearly massively more powerful than anything the humans can cobble together, have allowed themselves to be forcibly ghettoized for more than 20 years! I mean, a couple of those power armour things and a hundred 'prawns' with their lightning weapons should be enough to take on pretty much anyone.

But, if we ignore that, the notion of the mega-corporation trying to exploit the aliens for their weapons technology came across as a bit cliche, as did the entire hero's 'turn' when he, now marginalized by the power group he once represented to the underdogs he is now part of, sees the light and sacrifices himself to save the alien and his son.

Frankly, this film wouldn't have garnered nearly as much attention if not for Peter Jackson's name being attached to it, and the promise of some sort of overarching (and possibly controversial) message as suggested by its being set in South Africa. If they were intending for the story to be allegorical, it was clumsy at best.

Hopefully Blomkamp's next attempts will be a bit more ambitious. Overally it feels like District 9 flirted with greatness but fell short simply because it didn't push hard enough. It flirts with a lot of ideas and content without exploring them enough to present anything truly powerful or even lasting.

If you saw it, how did you feel about it?

Jesse Alexander interview  

Posted by Raphael

I had the good fortune to meet Jesse a few months ago in a really casual setting and spend some time soaking up his thoughts on story. It was an awesome experience -- he has this really cool energy that is simultaneously manic and calm, and it's really infectious. I left our conversation feeling really invigorated about what I do every day, which is to try to find new and better ways to get video game players engaged in a storytelling experience.


Anyways, I noticed on Jesse's blog that he did an interview with io9 where he talks about his new show, Day 1, and discusses some of his influences. Check it out.

Switch!  

Posted by Raphael

Much to the surprise of my friends and family, I've made the switch to Mac! I'm typing this entry from my shiny, new-smelling Macbook Pro. It's an absolutely beautiful piece of industrial design and really forces you to ask the question -- why shouldn't a computer look and feel like a piece of functional art?


In any case, I intend to keep my desktop PC for gaming, and switch the bulk of my writing work to the Mac. I'm still in that early awkward stage where I can't find anything and I'm having to try to unlearn some of the little habits and quirks I've developed over years and years of using Windows. I'm actually finding it quite refreshing to have to learn some new software and shift my way of thinking about workflow, etc.

When I have more time, I intend to delve into Keynote more deeply, since I imagine it's a hell of a lot more intuitive than PPT and therefore it should (theoretically) result in some interesting new presentation styles for me. I've found that in so many of the presentations I've been doing for work lately, my brain has adapted to thinking of ideas and information in terms of how PPT works, versus simply using it as a tool to express those ideas and information. In many ways PPT has been extremely useful -- like a whiteboard or Mindmap is useful -- in that it forces you to be organized and methodical in how you think and work, but in other ways I suspect it's been constraining.

In terms of the packaging and user experience of using a Mac for the first time, I think we game developers can learn a lot from Apple. Clearly, you are meant to feel like using this computer is an enjoyable experience, catered to your preferences -- it's all about you. And, while the consoles have made great strides towards this in services like Xbox Live! and the PSN, once you're in the games themselves it's still a bit of a free-for-all. We should remember that the entry into a game experience is like the entrance to a beautifully architected building -- it's meant to be an experience in and of itself, designed to put you in a frame of mind to fully appreciate and open yourself to what's to come. If Apple can do that -- and imbue an inanimate piece of technology with such a pleasurable aesthetic -- we should be able to use all the tools at our disposal (visuals, audio, interface, etc.) to do the same.

When was the last time you had an emotional reaction (that wasn't frustration or disappointment) to your first entry into a new game experience. I'm talking about the pre-game feelings -- the animated logos, the music stingers, the main menu, etc.? A reaction that really put you in the right frame of mind for the experience that was to come?

So Say We All?  

Posted by Raphael

Warning....MASSIVE SPOILERS AHEAD!!!

Not sure if any of you caught the last episode of Ronald Moore's re-imagined Battlestar Galactica TV series. I got hooked on this show a couple of years ago and have been playing catch-up ever since. I found the show to be very fresh, the writing to be quite good, and the plot lines to be compelling.

Looking back on five years of episodes, I must say I still enjoy Season One the best. That's where I think the show really shone because it remained pure to the core of the conflict -- being on the run from the Cylons, being the underdog, the last bastion of the human race, having to always scramble to stay one step ahead, having to improvise, fight, fear, love, hate, etc., and sqeeze every last bit of human ingenuity left in their sad tired bodies to stay alive against an overwhelming force bent on their very extinction.

I won't complain about how the show tended to exhibit a lot of soap opera-ish qualities at times -- after all, despite my best attempts to convince my wife that we were sitting on the couch together to watch the next episode of a great science-fiction show, she and I both knew that we were watching it primarily to see how the various relationships -- always complex, always fiery -- would evolve in this next episode.

I suppose it's not fair or reasonable to expect that a show that has entertained for so many years -- primarily due to being able to juggle several tangentially related plot-lines and convince us that they were going to somehow connect them all at some point in the future -- would manage to meet or satisfy our massive expectations. Aside from having kind of lost the threads of the 'core story' for the past season or so, I'll have to admit I was kind of blindly following the show believing that at some point, my loyalty would be rewarded.

Imagine my disappointment, then, with the final episode!

I've tried to make sense of the contents, unsuccessfully. Aside from the first half -- the battle against the Cylon colony ship -- which was visceral and incredible and reminiscent of Season One battles (and frankly, highlighted how little the show has focused on this kind of action over the past couple of years, preferring to focus on a lot of internal struggles which, frankly, are a lot less compelling to me for being so damn drawn out and melodramatic at times) -- the episode was a convoluted mess of flashbacks mixed with aftermath recaps and the occasional shot of (gasp!) present day!!! I mean...WTF?

I feel it's a sad statement on humanity's struggle, and a relatively cynical conclusion, that after all these years of fighting to get to the safety of their paradise, the first thing everyone wanted to do was get the frack away from one another and head off to live like hermits.

Of the mess of flashbacks, the best I could figure out is:

  • Roslyn's story was to cement the reality that she really had nothing to lose and no family to mourn when Caprica was annihilated by the Cylons; I'm not sure how this reveals anything meaningful about her character except perhaps explaining how meaningful it would feel for her to have found, in Adama, someone she could feel a deep and familial connection with
  • Same story for Adama really; his flashbacks in the strip club with Tigh made me feel borderline uncomfortable, but clearly he had nothing going on back on Caprica and getting assigned to the museum-worthy Galactica was probably the best thing he had going for him
  • Lee and Kara -- really, we see a pattern of behaviour that is repeated over and over (for both of them) throughout the show, to the point of being irritating. I must admit that while I really liked these characters through the first two seasons, they started to really grate on my nerves in the later years of the show, to the point where I feel they were both essentially sidelined and made fairly irrelevant.
  • Cylon reconciliation WTF? Chief Tyrol's revenge for Kali's death throwing the possibility of human/cylon reconciliation out the window WTF? Hera as human/cylon hybrid/messiah WTF? Baltar and Caprica 6 existing to guide Hera to the Galactica CIC at the defining moment WTF? I'm sure the writers had that exact moment in mind when they started that whole Concert Hall stuff back in...was is Season 2 or 3?
  • Starbuck as angel and ghost? WTF?
  • Fast forward 150,000 years and we see...what was that, Time Sqaure? Japanese robots as Cylon prototypes? WTF?
I'm not as bitter as I seem about this. The show provided me with a lot of entertainment over the past couple of years, but honestly...this finale feels sloppy and doesn't really do justice to the quality of the show as a whole, and the follow-up interviews I've read with RDM where he's asked to explain some of the decisions made as they were wrapping up the mythology in the last 10 episodes are downright silly ("whoops...we never even thought that people might think the "shutdown Cylon Artist Daniel" and the "Daniel as mystical piano-man and Starbucks' father" were meant to be the same character -- our bad for not being more fucking clueful about how we've trained our fans to pay attention to details that we actually don't think about for more than 2 seconds!!!"), and personally make me quite angry. I mean...jesus man...have you no pride! You knew a year or more ago that the show was going to be ending in a season...surely you could have taken the time to plot out a more elegant exit.

Can anyone recommend a good TV show as a pallette cleanser?

About Me

My Photo
Raphael van Lierop
Montreal, Canada
I've been working in the industry since 2002, and have been a creative director, producer, writer, and designer on some pretty cool projects.
View my complete profile

LinkedIn

Ludography

  • - Unnanounced Ubisoft Montreal Project
  • - Earth No More
  • - Prey 2
  • - Incarnate
  • - Company of Heroes
  • - Company of Heroes: Opposing Fronts
  • - Warhammer 40,000: Dawn of War
  • - Dawn of War: Winter Assault

Blogroll