Game Development Community

keeping track of your design by creating a user manual

by Phil Carlisle · 12/19/2005 (12:46 pm) · 11 comments

One of the issues I have with explaining design details to other members of my team, is that I absolutely HATE writing formal documentation.

I dont particularly know why, but it always seems that writing formal docs takes more time than just writing quick descriptions of things or making a quick sketch for a particular idea.

However this week I've found another approach to the problem: Writing a user manual!

Ok, it sounds hokey, but for some reason I can mentally make this part of my work schedule and just get it done easier because its for the final documentation that will ship with the game. Dont get me wrong though, this isnt some 100 page tome. Its simply a "how to use the software and what to expect from the controls" sort of document.

In fact, its almost entirely the kind of thing you would like to know about when designing the game!

For instance, with our current sports title (its untitled as yet, we're currently just using blocks for everything), I wanted to detail exactly which controls did which particular type of shot. How we would create things like pre and aftertouch. How powering up shots would work etc.

Strangely enough, thats exactly what the user, at least those who dig into manuals, would like to know!

So here I sit, writing "when you press button A, then keep it held and press button B, youre shot will change from a lob to a smash" kind of statements. Which are both design doc and manual fodder. I figure if I write it in the style of a manual, then any teammates should be able to grok what I mean when it comes time to implement features. This also works for things like menu flow and control.

On the subject of sports games, of which we have many planned. I dont know if youve noticed, but the MARIO branded sports games, all have a particular design of which I'm normally a fan of, have gotten into a definite design rut of late.

Let me explain a bit. You see, I've been casting around looking for design and style ideas from various sports titles and one of the obvious sports title franchises which fits my target audience style, is the nintendo sports titles based on the MARIO world. That is, cartoon cutesy style with arcade style gameplay and lots of user feedback. However they all are starting to exhibit such common behaviour that if one has a flaw they all have a flaw. Thats the case I'm going to explain now.

See, for the most part, the mario games are VERY playable, they have great control systems, are very responsive and although shallow sometimes they are very entertaining. But then comes along a design decision which is so mind-meltingly stupid I cant believe they made it.

Enter the "Special Move Shot".

Yes, that dear old character-dependant "Special Move" is a source of utter amazement to me. That nintendo would be so stupid as to break the flow of the action of a game simply to allow some character based special move shots is astounding. I dont mean just break the gameplay a bit, I mean stop it dead in its tracks!

Now I can definitely understand where they are coming from with this idea. Basically its "yeah, lets get each character to have a special move, so that they are totally different and relate the character to the player better. The cynical side of me thinks that this is merely a ploy to sell more merchandizing by simply reinforcing the player->character connection.

But to make these absurdly long special moves during which GAMEPLAY HALTS! just to play the animation?

And this isnt in just one game, oh my no. Its in Mario Tennis, Mario Baseball, Mario Soccer and probably a few others. Whats worse, is that usually the "special move" shots are just about unstoppable! So you get this powerup->specialmove->win triad going which would make me want to drop the game in a second.

I guess what most people do is have a gentlemans agreement to never allow specials.

Personally, I'm going to rip off the flavour and control schema of the Mario sports games almost wholesale for my designs. But one thing I'll definitely be leaving out is the special moves which block any player inputs!

Oh, I should have a picture, but the blocks really arent that much to look at! after xmas maybe :))

Oh, and the AI pack is coming on great. I've broken apart most of the suport code and have been fixing it into the 1.4 codebase at a deeper level than before. so basically you can have AI based gamebases, shapebases, players, vehicles, everything!!!

And Air Ace is back and alive again after KO fixed the damn camera jitter bugs. More testing on that over xmas break too!

#1
12/19/2005 (2:01 pm)
Hey Phil, I agree on the manual writing thing.

I've been doing the same thing but also expand that idea out to what will eventually become the web site content on game features and play. That way you use the same base document and then by applying section choices and minor formatting changes you can server three purposes:

1. Design Doc
2. User Manual
3. Web Site Content

That document coupled with in-code technical documentation pretty much covers it all and IMO no formal documentation needs to be done.

Good luck with the sports games, sounds like a good approach.
#2
12/19/2005 (3:34 pm)
Woohoo on the AIPack and AirAce
#3
12/19/2005 (3:48 pm)
It sounds like you're using the end-user manual as a kind of functional specification. You should read up on some of the articles at http://www.joelonsoftware.com, especially the ones on writing functional specifications. He's got some good advice there to make it easier to write, and easier to read for those implementing the spec.
#4
12/19/2005 (4:33 pm)
I believe Phil has uncovered a great approach, not unlike the difference between writing comments for comments sake and writing useful comments in code. Thinking in terms of how the user wants to use things focus's you on what you want versus how you implement - the difference between the tech spec and the functional spec.

I've said it before, but I love how Phil goes free-form on his thought process, listing out every detail of what he's thinking.

Keep 'em coming, Phil!
#5
12/19/2005 (4:50 pm)
Actually I was about to do the exact same thing in the next few days. I have a design doc - but a user manual gives you valuable insight into use cases and therefore the overall requirements for your game.

I've been reading through Software Engineering for Game Developers and it seems like you're taking a pretty close approach to what is suggested in the book (minus all of the Software specific stuff).

I hope it's working well for you ;).

- Eric
#6
12/19/2005 (7:47 pm)
Write the strategy guide, too, so that you can find exploits :)
#7
12/19/2005 (10:18 pm)
Shyeesh, someone just doesn't know how to handle the special moves. I had no trouble dealing with them in (Mario) Tennis (Tennis just needed a finite method for using them) or Baseball, and I just started playing Strikers where they are instant goals, but you need a lot of space and timing to hit one right. I can't get into the realistic modern sports games and my favourite sports game ever is still Ken Griffey Jr. Presents Major League Baseball on the SNES, which had quick 2d pitching and tight arcadey fielding. The only problem most of these games end up with, is the simplified mechanics can limit the variety of experiences you'll see. So you do have to make a balance between fun arcadey control, but still giving the game some depth.
#8
12/20/2005 (4:14 am)
This is how I met my wife.

She was hired to write the user manual. The software wasn't yet finished. She said "ok ... I'll write it from the design docs". We laughed. There was no design doc. So she wrote one.

True story.

- Paul
#9
12/21/2005 (5:55 am)
I would like to see GG host a web tool for this issue. What it could do is let you have secure project management. You can control who get's invited etc. Has some maybe generic I AGREE stuff (NDA, waivers, blah blah.. ok grey area yea). Secure shared files (with incremental backup in case someone goes nuts on the team). Oh well just brain dumping. And it ties into like Mantis so you can bid out bounties for things.

But instead of 10 logins I want it all on GG's site in 1 mega tool. Bacon and Lettuce plz.

Edit: I could be tagged "cold" so that GG developers can use it for a game plan / manual as Phil talks about
here. As well as full blown "hot" networked project..
#10
12/23/2005 (1:21 pm)
The user manual approach is something I've been doing for a while. It's a very good way to break down the gameplay without getting into too much technical crap and bogging down the document. It keeps it practical and usefull for the reader. The only issue that this works well for standards that have been established as you can compare your manuals to others than have been created for things that you have missed. For new genres it can be more practical to get things going with a full document. However, a design doc is still a requirement for a publisher, but could be better supported by saying; here's the user manual, here's the design doc. Read the user manual and you'll understand our game, the design doc only shows we can make it and everything is setup.

Actually, I think a wiki like environment is really good too, where you can quickly edit things and then export it to a nice document format. It works well for small games!

Keep on rocking!

Toby.
#11
12/29/2005 (9:48 pm)
Phil,

I have been doing this for years on all my personal projects.
There is something about writing out instructions and the sort that get your mind around what can be added and what can be kept out.

Plus you are like ten times more likely to stick to the meat of your program as it is harder to go back into your documentation and have to re-write it.

I'm glad you like the idea also