I’ve written lots of design documents…Hundreds and hundreds of pages of design documentation that occasionally gets turned into a nifty product. It goes without saying that the vast majority don’t get read unless they are essential to the final implementation. That is a start, but I’m always looking for better ways to convey ideas and get people on board.
What is the goal of a design document?
Not all design documents are created for the same purpose. The two most common ones I run into are as follows:
- Convey implementation requirements: “Put this feature C at (X3, Y4) and hook it up to widget B!”
- Convince: “Let me tell you a tale about widget B and how cool it would be to implement!”
The first is the traditional use of a design document and tends to focus on lists of implementational details. If it isn’t specified in the design document, it isn’t going to get done. So people tend to overdo the exhaustive detail. Honestly, it is no wonder that people avoid reading such literary monstrosities unless forced to by whip cracking managers.
The second is quite common, but rarely acknowledged as part of the development process. Teams don’t always get to meet communally on every feature and usually one or two people have a strong understanding of a particular feature’s benefits. These feature champions often write the design documents, the one touch point that is available to all team members.
Problem: No one reads it.
Here’s the problem. If you write the first draft of a feature design in the highly specified fashion promoted as a ‘good design doc’, no one will read it and it becomes hard to build any sort of excitement around the idea. I’ve seen hundreds of great design ideas wither on the vine because highly technical design docs are tossed over the fence and no one ever really grasps the full picture about why the feature matters.
Problem: Too expensive to create
Documents intended to convince are usually created in the early stages of development. Ideas are rough and speed is essential. Often you’ll need to bang out a feature concept in a spare 30 minutes and then submit it to the team. If the authoring medium is too difficult to use (raw HTML comes to mind) no one will take the time to put their design thoughts down.
How do we write a design document that convinces? (And isn’t horrendously boring to read or expensive to create)
A blog as a narrative design document
One of the things I like about blogs is that they have an inherently linear narrative built into the structure. “Monday, 8:42am: Today, I ate bacon.” followed by “Tuesday, 8:15am: This sounds like a bacon day too” Each post gives a sequential snapshot of a person’s life.
What if a blog could tell a reader friendly narrative story about a product design? Blogs are easy to write and generally reader friendly. The text doesn’t have to be structured like a novel (few blogs are). But like a story, you can mention relationships between items coming up in the future. You can use more casual engaging language. You can lead the reader through the beginning of the project all the way to the end.
How iterative development maps onto a blog
Iterative software development lends itself quite well to a story where each iteration is a chapter. In iterative development, you typically follow a standard pattern
- Identify the big story
- Identify the most important things that need to be done first from the customer’s perspective.
- Build it.
- Ask what needs to be done next based off your current project status and customer needs.
- Repeat with a new iteration.
What you end up with is a rich explanation of the rational behind each feature. As you add features, your are building a narrative leading towards a final goal or product state.
The role of comments
A post in a blog is an authoritative statement of reality. A page of a design must also be authoritative. However, a design intended to convince others must also have a feedback mechanism to address concerns, worries and other ideas. The comment section of a blog is perfect for this. Each ‘chapter’ of the design is up for public discussion. When changes must be made, the author of the post can go back in and make the revisions.
Specifying the Blog-based Game Design
What are the elements of a blog-based game design?
- Introduction: The big picture on why this product matters. Who does it serve? Why should they care? Why should the developers care?
- Walkthrough: A simple story illustrating how the game plays. This is an example illustrating the big story.
- Core Systems: What are the core game mechanics that the player will be engaging in. What systems are required to build this core game mechanics?
- Release: This post describes a minimum bundle of features necessary to create a truly playable game. The game can be broken, but everyone on the team needs to feel the vision and understand what happens next.
- Feature: What is the first feature that will make this game come alive? Include descriptive example text. No lists please.
- Next Release: Celebrate the previous Release and do a virtual post mortem. Discuss what needs to happen in the next release and the features necessary. Tie it all back into the big vision. Repeat!
- Conclusion: What happens at the end of the project? What is the result? Sell the reader on the fact that all this effort was well worthwhile.
All these posts are kept to a manageable size and have a narrative writing style. If the post is too long, chances are slim someone will implement it without losing sight of the big vision of the product.
Benefits of Blogs as Design documents
- Easy to author: No fancy formating, just bang out the text. Sweet.
- Searchable: Looking for something? Just search the blog and you’ll find it.
- Linkable: Want to send someone just a single feature. Forward the link.
- Comment Friendly: Nuff said.
- Speaks with one voice: The posts are the authority. Everything else is just noise.
Problems with Blogs as Design documents
- No Autolinking: Typically a designer will build up a unique vocabulary as the design develops. It can be useful for the reader to be able to access these words. Wiki-style autolinking would alleviate this issue.
- Linear structure limits non sequiteurs: Traditional narrative plays with this issue constantly. Thankfully most readers can deal with a brief side jaunt over to a different story thread before coming back to the main story line of the design.
- Lack of index: As documents get super long, a blog can become hard to navigate without an index or tagging system of some sort. Some blogs solve this, but Blogger doesn’t. 🙂
A Test Case: Putting theory into action.
I have a short (13 page) design document for a casual strategy game called SpaceCrack that I’ll be posting on LostGarden.com over the next couple of months. I’m going to ‘blog the design’ and see how some of my theoretical structures work in practice. My hope is to hone in on a ‘readable’ game design document that can be easily shared with a wide group of people.
As part of the bigger picture, I’ve noticed that professional complete game design documents are a rare thing on the web. This whole exercise is a stab at shedding some light on a traditionally black art of game development.
PS: A side note on Wikis
I’ve used Wikis for design documentation recently and like them a lot. The change tracking, communal commentary, and auto-linking are wonderful. Right now we are using them as our design document method at the office. They are the best thing I’ve seen so far for writing design documents. The two topics that are painful
- Poor at convincing: Wiki’s lack narrative structure that makes them difficult navigate and read. Instead of one argument the flows from beginning to end, there are multiple ways of reading the same document. Nothing ‘builds’. Instead the reader is left with a spattering of discrete information.
- Lack of a single voice: Wiki’s nature is that they are quite chaotic at times with people jumping in at random points and offering a wide variety of comments, ideas, etc. This is mentally invigorating but can be difficult to parse. Often developers are left scratching their heads and thinking “So, what are we supposed to do?” A good gardener can help, but this generally results in the loss of the original comments (even when you have versioning, no one reads the old versions)