Improving your Documentation

Game Design is about the merging of ideas and the creative evolution of complex entertainment software from idea through delivery.  Nothing in this process is more important to the Designer than effective communication and memory over long periods of time.

Enter the role of documentation.

Preface

Trying to improve your documentation is a long and arduous process.  Unfortunately, I don’t know of any way to build these skills without practice and critique.  If you have any friends who are Editors or Writers themselves, they can often give you good feedback — but be careful of those who work solely in creative writing.  Technical writing is not creative writing, though they share some parts of their skill sets.  So I have to give you this advice: if you want to improve your technical writing, write more.

What’s the point?

Technical writing differs greatly from other forms of writing in its purpose, and it’s important to recognize that purpose: communication.  All writing is about communication, but technical writing begins with a clear understanding of the purpose of the document you are writing.  Here are some examples:

Game Design Document: The purpose of this document is to describe completely all features and illustrate clearly the functionality of the game in development.
Pitch: The purpose of this document is to sell your ideal to a lead, prospective client, investor, or publisher.

Keep it on track

Keep the goal in mind the entire time you are writing the document.  Information not relevant to the goal will only create noise, making it more difficult to understand.  As you write, it will help you decide, “Does this information need to be here?”  It is easy to litter your documentation with stray information that comes up while you write, but probably isn’t that useful in terms of the document.

On the same point, put things where they belong.  If you have a section on Enemies, make sure it contains ALL of the relevant information on Enemies.  Don’t put your Enemy Statistics in one section and your Enemy Descriptions in another unless you really have to.

Show, Don’t Tell

We are visual creatures, and like to communicate visually.  If you’re having difficulty describing something in your text because of its complex or abstract nature, sketch it out.  Then put that sketch into the document.  A little forethought into the presentation of your information can go a long way.  Try to put any “listed” information into bullet points, or, even better, a chart.

Prepare for questions

Questions on your documentation are great.  They lead to better understanding and clarity for all.  When someone asks you a question about the documentation, however, be sure to add that information to the doc again later.  Either that, or prepare to answer the same question over and over again.

Make it interesting

If your documentation is dry and unfeeling, no one will read it.  Sure, they’ll skim through it and get a feel for the gist of it, but they won’t digest the information and understand it the way you do.  Your game is going to have a personality, so try to inject that in your writing.  But, don’t let it get in the way of communicating the information.  Communication is king.

Grammar and Spelling

Don’t kid yourself.  It was easy to blow this off in high school and even college using spell check on your essays, but now you’re a professional, and you’re writing to communicate.  Spell check isn’t as good as you think it is, so don’t rely on it.  Even one misused term can derail your reader significantly, so write like a professional.

When in doubt, Document it!