Skip to main content

Writing for games

Forum

Just a query.

Is anyone familiar with writing conventions for video games? Are there any? Or is plot just something they give work experience kids to do?

I'm considering doing my honours thesis on this topic. It's a ways off yet, but I figure it's never too early to start. I don't think it has been widely explored. Fuck, I've played enough games to know that it hasn't.

Gimme info!

Submitted by Jacana on Tue, 15/08/06 - 7:02 PM Permalink

Have you had a look at books on Amazon and so forth. I am sure that I have seen books on the topic.

Another option - I am on a mailing list (female orinted) that I know has some writers. Maybe getting in touch with people there could be useful..?

Submitted by Jackydablunt on Tue, 15/08/06 - 7:25 PM Permalink

One thing I do know is that most companies treat it very differently from one another. In the last company I did probably 4 game docs (give or take) and I did all of the writing for those, and shared it for another, the place I'm at now its very much shared, in others they hire a specific guy for the job (I think Krome does, or did at least). As for the process of game writing, I could tell you how I approached it personally but I've never done things to convention so it may not be too helpful for a thesis. Of course it also depends entirely upon the game you're making and the team you're with.

Submitted by Sorceror Bob on Sun, 20/08/06 - 5:28 AM Permalink

Juullees

They sure do, I am rather ashamed of hte texture work on the croc haha.

Submitted by Killa Dee on Wed, 23/08/06 - 2:21 AM Permalink

Hey! Long time, I think I have the model file somewhere.Hehe[;)]

Jackydablunt, would you be able to post up any examples of your works?
I would be very interested to take a look. How detailed are most of your game design docs?

I've been working on a couple of game designs myself, but I?m not sure how much detail they require (I guess it depends on the job).

Submitted by Jackydablunt on Wed, 23/08/06 - 5:03 AM Permalink

There's no answer at all to what companies require man, Design's gotta be one of the most obscure positions to get (just ask Caroo), and to work in. The first gig I got, I started as an artist and moved in-house to Design simply because I had good ieas and knew how to present them. The current job I'm at now I got because of a collection of skills that I guess my boss saw potential in.

As for how to write a game doc? christ knows, some companies write singular massive ones with narrative and VO line counts and all the above, others prefer to write a whole heap of little ones, some print out textbook sized GDD's some upload to wiki... They DO need to be detailled but you have to know where to put that detail and when, the best thing I can suggest off handedly is to separate narrative from assets and mechanics, describe them all separately.

Look into the Design forum, there are a few discussions going on there regarding this very issue. Sorry I'd give a better reply but I've just realised it's like 7pm and I'm still at work, so screw that I'm outta here :)

Submitted by Caroo on Wed, 23/08/06 - 6:19 AM Permalink

*puts on a pair of intelligent looking spectacles*

It's my view that this utter luck of identification of what a game designer is, is what makes it so hard for anyone who is not yet a designer in the industry to actually becoming a designer. You can have skills in one area that?ll get you a job in one studio but will be absolutely meaningless to another. The little dot points on studio job websites don?t help much ether.

And then there?s the issue of getting noticed and recognised! ooooh don?t get me started.

But we?ll stay away from ranting for now.

On what to write on documents? You have to get creative. Knowledge and Detail is power in writing a good design document. The mechanics and outlay of a design document is never fixed and is diverse and different from man to man to woman.

But whatever way you write it. Here?s what to keep in mind:

? If the document is big. Have a contents/index and number your pages.
? Spaces are your friend in a document. Don?t cramp everything to close together.
? Spelling has to be readable [I fail at times at this] and more importantly grammar must also be top notch.
? Like Jacky said. Don?t mix emotion and story with technical and mechanics.
? Be detailed where it?s needed. Don?t use a page to describe that the texture on a wall is going to be grey concrete when that time and page could be spent writing about a massive cannon you have to blow up.
? Pictures and plans of what your trying to convey only helps. But use it wisely as its time consuming.
? Be flexible in your designs. For both the valuable ideas others have and for your games time/budget.

To me. These points are very important. And I hope that clears a little up for you mate.

Now if you excuse me I gotta finish off another small UnrealED map and sometime this week do some document writing of my own. Don?t worry. As always it?ll be up on the design section of sumea. Wish more people would post replies though.

Cheers.

Submitted by Sorceror Bob on Wed, 23/08/06 - 1:46 PM Permalink

Julz - Ahh man, yeah I look back and shudder some days. My artistic style left a lot to be desired. :P

I have done some research into game writing, and I predict that there will be an industry standard for this in place within five years. It's all going the way of the film industry. I think if people want to write for games (write, not design), they're going to have to learn to write scripts first.

Scriptwriting = poo. But it's insanely structured poo written for a visual medium. Mark my words!! It'll happen.

Submitted by Caroo on Wed, 23/08/06 - 10:01 PM Permalink

quote:Originally posted by Sorceror Bob

Julz - Ahh man, yeah I look back and shudder some days. My artistic style left a lot to be desired. :P

I have done some research into game writing, and I predict that there will be an industry standard for this in place within five years. It's all going the way of the film industry. I think if people want to write for games (write, not design), they're going to have to learn to write scripts first.

Scriptwriting = poo. But it's insanely structured poo written for a visual medium. Mark my words!! It'll happen.

I strongly agree with this. Not so dramaticly but yes designers will have to face in the next few years where they wish to go with themselfs. To ether make the storyline or the gameplay mechcanics. I guess it comes down to the designer in question. A lot of designers i know of are first and foremost writers. So gameplay designers are going to be very desired in the next few years by my prediction.

Thus why I'm heading in that direction.

Submitted by GuyBrave on Wed, 23/08/06 - 10:56 PM Permalink

I think as the industry matures, designers and writers will not be positions held by the same people, just like they are not in any other field. They are different disciplines. There may be some overlap, where a particular person has the skills to perform either role, but they would still be seperate jobs in bigger places at least. Just like back in the day, the programming and the art was done by the same guy, that does not mean that they are the same discipline. As the industry grew, there became the need and the facility for that sort of specialisation. Its a progression of that I believe, and in the not too distant future Im sure it will be common for most game studios to have their equivalent of a screenwriter on the staff.

Submitted by Maitrek on Thu, 24/08/06 - 3:58 AM Permalink

Uuh - I don't think that - within the definition of what a game is - there is *no* overlap between how the game 'mechanically' operates and how the narrative operates. I think that a good understanding of how the two can be used to complement each other as well as how they supplement each other is necessary - and simply annexing the two into separate roles would be ... well crap really.

Sadly i have nothing useful to contribute in the way of potential resources for your thesis Sorceror Bob - but good luck none the less!

Submitted by Jackydablunt on Sat, 26/08/06 - 1:49 AM Permalink

No you're right there, and I didnt mean separate them into separate docs and things (sometimes you do), I mean separate them in your mind, you have to know what you're writing and who you're writing it for. Once the production team knows the general jist of the story then the last thing they want is to sift through it again and again to get to mechanic descriptions, you have to know when it's needed and talk purely in context.

I also find it helps to write how you speak, use the same words and don't try to talk down or sound itellectual unless there are calls for it. Production teams hate reading docs so you have to make them easy to read, and author them as well so people know who to go to for more detail.

Submitted by Jackydablunt on Mon, 28/08/06 - 7:21 PM Permalink

Killadee, what aspects are you hoping to improve upon? It's just that in my opinion there's no real definite way to write a game doc, I threw out all thoes templates you get from gamasutra and stuff a long time ago. The last full doc I did was different from the previous, and that was different from the one before that. Some people here may be able to help you define certain areas though.

Dan

Submitted by Killa Dee on Sat, 02/09/06 - 1:45 AM Permalink

Hey, (sorry to bump this thread)

I would like to improve the structure of my half baked ideas/designs. I?m interested in any industry standards or practices that aren?t blindly obvious (like spelling and grammar). Examples of any game systems, flow, mechanics etc would really help. I have been surfing around for a while but any hot leads or links would be greatly appreciated.

Submitted by TartanBoy on Sat, 02/09/06 - 9:58 AM Permalink

quote:Originally posted by KILLA DEE

Hey, (sorry to bump this thread)

I would like to improve the structure of my half baked ideas/designs. I?m interested in any industry standards or practices that aren?t blindly obvious (like spelling and grammar). Examples of any game systems, flow, mechanics etc would really help. I have been surfing around for a while but any hot leads or links would be greatly appreciated.

Hi!

I visit this site now and again but I don't really post very often (too busy working!! :) )

Anyways, I've worked in the industry for around 12 years, been involved in design for the past 5-6 years. I've written many designs/proposals, so here's my tuppence worth. Hope it helps!

Try and include the following in your design (these are in rough order but it really can be mixed up).

An EXECUTIVE SUMMARY ? this is a half page description of the highlights of you game. Be a succinct as possible. Include: platforms, genre, what are the USPs (unique selling points) of the game.

KEY FEATURES ? list the key features of components of your game. For example:

- 3 Modes of play
- Multiplayer Options
- Innovative or proven gameplay mechanics (VERY IMPORTANT!)
- Realistic physics
- Exciting use of license
- Replays
- Stats Trackers

Don?t list every last detail here, just categorise so that now, everything you mention in your KEY FEATURES you?re can expand on. This really will be the meat of your design document and what?s in here will really be determined by the type of game you are doing.

Note: I put very important next to Innovative or Prove Gameplay Mechanics ? this is really where your game should be described. Anyone can write, ?we?re going to have great physics? or ?a fantastic story? ? all these things are great and sometimes important to a project?s success BUT describing the actual gameplay in detail is KEY to a cracking what the project is about.

Games take a long time to develop so you need to know what the CONTROLLING THEME of your game is and keep that creative focus. As a project progresses and people add ideas and opinions it?s easy to get lead down a side-street and then suddenly the game you are making is no longer the game you set out to make. So, make sure it?s clear in your proposal the creative direction that the game must go in.

Other things you want to mention:

CONTROLS: What is the controller layout.

CHARACTER: If it?s a character based product you really need to get out all the info you can about the main characters. What they can do, how they develop, what they look like etc. If it?s not a character based game, say it?s a SPORTS game or a CAR game then you really need to define the mechanics and feel of how the player controls the car/team/avatar/whatever.

USER INTERFACE: What do we need to show in terms of maps, HUD, etc.

STORY ? depending on the type of game there may be or may not be a story. How will it be told to the player? Cutscenes? Pre-rendered? In-game? Spoken dialogue?

VISUAL STYLE ? how you see the game looking. The art director of the project will ultimately decide this but as a designer you can suggest what you think here. (Pictures help ? i.e. create a mood board type montage)

AUDIO ? again the audio guys will play a large part in the final sound design, but this is the place to mention key audio features that you want ? whether that?s a classical music score, or a famous actor?s voice for dialogue.

HELP SYSTEM and TUTORIALS ? how does the player learn the game? Is there tutorials, in-game help? Explain it here.

GAMEPLAY WALKTHROUGH ? good to give people a feel for the game, describe yourself playing it. Again dependent on the game type you may describe a minute section, or you may have to give the overview of an entire quest or whatever!

UNLOCKS ? How do you reward the player. What offers replay value?

LICENSE USE ? Could a license be attached to this project? If it is a licensed project explain why you design reflects the key values of that license.

TECHNOLOGY ? Again, same as ART and AUDIO, after the initial game proposal is written the code guys will take it apart and tell you exactly what can and can?t be done. I personally, come from a coding background so I do tend to give my high level thought on this, i.e. this project can build on technology from our previous game (always good).

As said prevously, good written skills are essential. Spelling and grammar are important - so if you need to improve these, then you better do so now. No creative director/lead designer wants to have to re-write or proof-read every thing you submit - they want to hire you so that you help get the game done, not hinder them.

Good luck with your designs!

Submitted by Jackydablunt on Mon, 04/09/06 - 7:25 PM Permalink

Yeah articulation is pretty much the most predominant skill you need. The primary rule I always go by when writing something for the top end of a game doc is the presumption the reader is not from the industry, doesn't play games, doesn't care or want to care about games, has no technical knowledge, and has to read the document while running out the door. The way you write a doc should be for all readers including thoes that may never read it. Keep it brief for thoes only scanning for the core points, yet descriptive and focused enough for the others who may take interest. Author the doc as well, possibly with the addition of your email address so people can ask you further detail.

Keep the detail separate, and to the back of the document or in separate appendicies whether they be docs or wiki. These are the parts written for thoes doing the work so thats where you write more attuned to them. If its a mechanic doc for coders then write like a coder:

- Keep it straight to the point
- Use steps and bullet points
- Coders dont care about other crap.

For artists you can deliver more emotionally depending on what it is you're describing.

And try to not be insulted when others don't read what you've written, or ignore the doc and make you step through it all in person when you easily have better things to do. You have to understand that just because that document may be your primary interest and focus, it doesn't mean that its theirs, in fact expect that it wont be. I'd say about 50% of what you write will be read by most people, and 20% will be actually absorbed, the leg work and personal communication is I think the key to design, not the document, and it's your approcability and ability to compromise that'll be the thing most required. The doc is merely the first step, Design it the delivery.

Dan

Forum

Just a query.

Is anyone familiar with writing conventions for video games? Are there any? Or is plot just something they give work experience kids to do?

I'm considering doing my honours thesis on this topic. It's a ways off yet, but I figure it's never too early to start. I don't think it has been widely explored. Fuck, I've played enough games to know that it hasn't.

Gimme info!


Submitted by Jacana on Tue, 15/08/06 - 7:02 PM Permalink

Have you had a look at books on Amazon and so forth. I am sure that I have seen books on the topic.

Another option - I am on a mailing list (female orinted) that I know has some writers. Maybe getting in touch with people there could be useful..?

Submitted by Jackydablunt on Tue, 15/08/06 - 7:25 PM Permalink

One thing I do know is that most companies treat it very differently from one another. In the last company I did probably 4 game docs (give or take) and I did all of the writing for those, and shared it for another, the place I'm at now its very much shared, in others they hire a specific guy for the job (I think Krome does, or did at least). As for the process of game writing, I could tell you how I approached it personally but I've never done things to convention so it may not be too helpful for a thesis. Of course it also depends entirely upon the game you're making and the team you're with.

Submitted by Sorceror Bob on Sun, 20/08/06 - 5:28 AM Permalink

Juullees

They sure do, I am rather ashamed of hte texture work on the croc haha.

Submitted by Killa Dee on Wed, 23/08/06 - 2:21 AM Permalink

Hey! Long time, I think I have the model file somewhere.Hehe[;)]

Jackydablunt, would you be able to post up any examples of your works?
I would be very interested to take a look. How detailed are most of your game design docs?

I've been working on a couple of game designs myself, but I?m not sure how much detail they require (I guess it depends on the job).

Submitted by Jackydablunt on Wed, 23/08/06 - 5:03 AM Permalink

There's no answer at all to what companies require man, Design's gotta be one of the most obscure positions to get (just ask Caroo), and to work in. The first gig I got, I started as an artist and moved in-house to Design simply because I had good ieas and knew how to present them. The current job I'm at now I got because of a collection of skills that I guess my boss saw potential in.

As for how to write a game doc? christ knows, some companies write singular massive ones with narrative and VO line counts and all the above, others prefer to write a whole heap of little ones, some print out textbook sized GDD's some upload to wiki... They DO need to be detailled but you have to know where to put that detail and when, the best thing I can suggest off handedly is to separate narrative from assets and mechanics, describe them all separately.

Look into the Design forum, there are a few discussions going on there regarding this very issue. Sorry I'd give a better reply but I've just realised it's like 7pm and I'm still at work, so screw that I'm outta here :)

Submitted by Caroo on Wed, 23/08/06 - 6:19 AM Permalink

*puts on a pair of intelligent looking spectacles*

It's my view that this utter luck of identification of what a game designer is, is what makes it so hard for anyone who is not yet a designer in the industry to actually becoming a designer. You can have skills in one area that?ll get you a job in one studio but will be absolutely meaningless to another. The little dot points on studio job websites don?t help much ether.

And then there?s the issue of getting noticed and recognised! ooooh don?t get me started.

But we?ll stay away from ranting for now.

On what to write on documents? You have to get creative. Knowledge and Detail is power in writing a good design document. The mechanics and outlay of a design document is never fixed and is diverse and different from man to man to woman.

But whatever way you write it. Here?s what to keep in mind:

? If the document is big. Have a contents/index and number your pages.
? Spaces are your friend in a document. Don?t cramp everything to close together.
? Spelling has to be readable [I fail at times at this] and more importantly grammar must also be top notch.
? Like Jacky said. Don?t mix emotion and story with technical and mechanics.
? Be detailed where it?s needed. Don?t use a page to describe that the texture on a wall is going to be grey concrete when that time and page could be spent writing about a massive cannon you have to blow up.
? Pictures and plans of what your trying to convey only helps. But use it wisely as its time consuming.
? Be flexible in your designs. For both the valuable ideas others have and for your games time/budget.

To me. These points are very important. And I hope that clears a little up for you mate.

Now if you excuse me I gotta finish off another small UnrealED map and sometime this week do some document writing of my own. Don?t worry. As always it?ll be up on the design section of sumea. Wish more people would post replies though.

Cheers.

Submitted by Sorceror Bob on Wed, 23/08/06 - 1:46 PM Permalink

Julz - Ahh man, yeah I look back and shudder some days. My artistic style left a lot to be desired. :P

I have done some research into game writing, and I predict that there will be an industry standard for this in place within five years. It's all going the way of the film industry. I think if people want to write for games (write, not design), they're going to have to learn to write scripts first.

Scriptwriting = poo. But it's insanely structured poo written for a visual medium. Mark my words!! It'll happen.

Submitted by Caroo on Wed, 23/08/06 - 10:01 PM Permalink

quote:Originally posted by Sorceror Bob

Julz - Ahh man, yeah I look back and shudder some days. My artistic style left a lot to be desired. :P

I have done some research into game writing, and I predict that there will be an industry standard for this in place within five years. It's all going the way of the film industry. I think if people want to write for games (write, not design), they're going to have to learn to write scripts first.

Scriptwriting = poo. But it's insanely structured poo written for a visual medium. Mark my words!! It'll happen.

I strongly agree with this. Not so dramaticly but yes designers will have to face in the next few years where they wish to go with themselfs. To ether make the storyline or the gameplay mechcanics. I guess it comes down to the designer in question. A lot of designers i know of are first and foremost writers. So gameplay designers are going to be very desired in the next few years by my prediction.

Thus why I'm heading in that direction.

Submitted by GuyBrave on Wed, 23/08/06 - 10:56 PM Permalink

I think as the industry matures, designers and writers will not be positions held by the same people, just like they are not in any other field. They are different disciplines. There may be some overlap, where a particular person has the skills to perform either role, but they would still be seperate jobs in bigger places at least. Just like back in the day, the programming and the art was done by the same guy, that does not mean that they are the same discipline. As the industry grew, there became the need and the facility for that sort of specialisation. Its a progression of that I believe, and in the not too distant future Im sure it will be common for most game studios to have their equivalent of a screenwriter on the staff.

Submitted by Maitrek on Thu, 24/08/06 - 3:58 AM Permalink

Uuh - I don't think that - within the definition of what a game is - there is *no* overlap between how the game 'mechanically' operates and how the narrative operates. I think that a good understanding of how the two can be used to complement each other as well as how they supplement each other is necessary - and simply annexing the two into separate roles would be ... well crap really.

Sadly i have nothing useful to contribute in the way of potential resources for your thesis Sorceror Bob - but good luck none the less!

Submitted by Jackydablunt on Sat, 26/08/06 - 1:49 AM Permalink

No you're right there, and I didnt mean separate them into separate docs and things (sometimes you do), I mean separate them in your mind, you have to know what you're writing and who you're writing it for. Once the production team knows the general jist of the story then the last thing they want is to sift through it again and again to get to mechanic descriptions, you have to know when it's needed and talk purely in context.

I also find it helps to write how you speak, use the same words and don't try to talk down or sound itellectual unless there are calls for it. Production teams hate reading docs so you have to make them easy to read, and author them as well so people know who to go to for more detail.

Submitted by Jackydablunt on Mon, 28/08/06 - 7:21 PM Permalink

Killadee, what aspects are you hoping to improve upon? It's just that in my opinion there's no real definite way to write a game doc, I threw out all thoes templates you get from gamasutra and stuff a long time ago. The last full doc I did was different from the previous, and that was different from the one before that. Some people here may be able to help you define certain areas though.

Dan

Submitted by Killa Dee on Sat, 02/09/06 - 1:45 AM Permalink

Hey, (sorry to bump this thread)

I would like to improve the structure of my half baked ideas/designs. I?m interested in any industry standards or practices that aren?t blindly obvious (like spelling and grammar). Examples of any game systems, flow, mechanics etc would really help. I have been surfing around for a while but any hot leads or links would be greatly appreciated.

Submitted by TartanBoy on Sat, 02/09/06 - 9:58 AM Permalink

quote:Originally posted by KILLA DEE

Hey, (sorry to bump this thread)

I would like to improve the structure of my half baked ideas/designs. I?m interested in any industry standards or practices that aren?t blindly obvious (like spelling and grammar). Examples of any game systems, flow, mechanics etc would really help. I have been surfing around for a while but any hot leads or links would be greatly appreciated.

Hi!

I visit this site now and again but I don't really post very often (too busy working!! :) )

Anyways, I've worked in the industry for around 12 years, been involved in design for the past 5-6 years. I've written many designs/proposals, so here's my tuppence worth. Hope it helps!

Try and include the following in your design (these are in rough order but it really can be mixed up).

An EXECUTIVE SUMMARY ? this is a half page description of the highlights of you game. Be a succinct as possible. Include: platforms, genre, what are the USPs (unique selling points) of the game.

KEY FEATURES ? list the key features of components of your game. For example:

- 3 Modes of play
- Multiplayer Options
- Innovative or proven gameplay mechanics (VERY IMPORTANT!)
- Realistic physics
- Exciting use of license
- Replays
- Stats Trackers

Don?t list every last detail here, just categorise so that now, everything you mention in your KEY FEATURES you?re can expand on. This really will be the meat of your design document and what?s in here will really be determined by the type of game you are doing.

Note: I put very important next to Innovative or Prove Gameplay Mechanics ? this is really where your game should be described. Anyone can write, ?we?re going to have great physics? or ?a fantastic story? ? all these things are great and sometimes important to a project?s success BUT describing the actual gameplay in detail is KEY to a cracking what the project is about.

Games take a long time to develop so you need to know what the CONTROLLING THEME of your game is and keep that creative focus. As a project progresses and people add ideas and opinions it?s easy to get lead down a side-street and then suddenly the game you are making is no longer the game you set out to make. So, make sure it?s clear in your proposal the creative direction that the game must go in.

Other things you want to mention:

CONTROLS: What is the controller layout.

CHARACTER: If it?s a character based product you really need to get out all the info you can about the main characters. What they can do, how they develop, what they look like etc. If it?s not a character based game, say it?s a SPORTS game or a CAR game then you really need to define the mechanics and feel of how the player controls the car/team/avatar/whatever.

USER INTERFACE: What do we need to show in terms of maps, HUD, etc.

STORY ? depending on the type of game there may be or may not be a story. How will it be told to the player? Cutscenes? Pre-rendered? In-game? Spoken dialogue?

VISUAL STYLE ? how you see the game looking. The art director of the project will ultimately decide this but as a designer you can suggest what you think here. (Pictures help ? i.e. create a mood board type montage)

AUDIO ? again the audio guys will play a large part in the final sound design, but this is the place to mention key audio features that you want ? whether that?s a classical music score, or a famous actor?s voice for dialogue.

HELP SYSTEM and TUTORIALS ? how does the player learn the game? Is there tutorials, in-game help? Explain it here.

GAMEPLAY WALKTHROUGH ? good to give people a feel for the game, describe yourself playing it. Again dependent on the game type you may describe a minute section, or you may have to give the overview of an entire quest or whatever!

UNLOCKS ? How do you reward the player. What offers replay value?

LICENSE USE ? Could a license be attached to this project? If it is a licensed project explain why you design reflects the key values of that license.

TECHNOLOGY ? Again, same as ART and AUDIO, after the initial game proposal is written the code guys will take it apart and tell you exactly what can and can?t be done. I personally, come from a coding background so I do tend to give my high level thought on this, i.e. this project can build on technology from our previous game (always good).

As said prevously, good written skills are essential. Spelling and grammar are important - so if you need to improve these, then you better do so now. No creative director/lead designer wants to have to re-write or proof-read every thing you submit - they want to hire you so that you help get the game done, not hinder them.

Good luck with your designs!

Submitted by Jackydablunt on Mon, 04/09/06 - 7:25 PM Permalink

Yeah articulation is pretty much the most predominant skill you need. The primary rule I always go by when writing something for the top end of a game doc is the presumption the reader is not from the industry, doesn't play games, doesn't care or want to care about games, has no technical knowledge, and has to read the document while running out the door. The way you write a doc should be for all readers including thoes that may never read it. Keep it brief for thoes only scanning for the core points, yet descriptive and focused enough for the others who may take interest. Author the doc as well, possibly with the addition of your email address so people can ask you further detail.

Keep the detail separate, and to the back of the document or in separate appendicies whether they be docs or wiki. These are the parts written for thoes doing the work so thats where you write more attuned to them. If its a mechanic doc for coders then write like a coder:

- Keep it straight to the point
- Use steps and bullet points
- Coders dont care about other crap.

For artists you can deliver more emotionally depending on what it is you're describing.

And try to not be insulted when others don't read what you've written, or ignore the doc and make you step through it all in person when you easily have better things to do. You have to understand that just because that document may be your primary interest and focus, it doesn't mean that its theirs, in fact expect that it wont be. I'd say about 50% of what you write will be read by most people, and 20% will be actually absorbed, the leg work and personal communication is I think the key to design, not the document, and it's your approcability and ability to compromise that'll be the thing most required. The doc is merely the first step, Design it the delivery.

Dan