Featured Blog

Documentation a Necessary Evil

I discuss why documentation is needed in the game development cycle and how it can be improved and improve the game dev cycle.

Originally posted on:

Hey Team,

(Disclaimer: these are my opinions and only my opinions)

Hope everyone is doing well making/playing the games they love. After talking about mechanics, design theories, etc. I have decided to shed some light on an area of design which is not spoken about enough, often overlooked, despite it being an integral part of the design. (I know why, because it is not most fun part of the job, to be honest)

What got me thinking about this part of the design was a flashback to my very first post which started my journey on to blogging ( It was about communication, how it is so essential to communicate with your team. Despite the team size, communication can break down so fast which can cause Huge issues. Now there are so many ways to communicate, which I touched upon briefly in my previous blog, one of these methods was DOCUMENTATION.

Documentation is not spoken about much due to the fact that it is often the least exciting part of the design (In my opinion at least). Sometimes some documentation is never updated when it should be or it was done retrospectively.

Now if I am being honest, I am not a fan of documentation but I know that it is extremely important when it comes to making video games. Now some of you may be thinking:

Well, I am glad you asked young Keanu Reeves (great hair). There are many reasons, so allow me to tell you them:

  • Communicates to all members of the team: no matter if you are a large or small team, communication can and will break down. I have worked in teams of 2 all the way up to 1000, it all breaks down at one point. With documents, you can constantly send them out to everyone so they can see what has been changed/added. (sad part of documentation is not everyone will read it) It does bring teams together from different departments as you may wonder what for example animation is doing?  Yet with these docs, you will know.
  • Spreading the knowledge: Now this is very important, as many people will be doing roughly the same thing whether it is using a certain tool to create a world or scripting missions. With having documentation on how to use certain tools, the team can become proficient and learn together even being able to help teach one another. If this knowledge is not shared, then suddenly the knowledge owner leaves then it will cause issues for you and your team in the long run.
  • Communicates clear vision: Now this is one of the most interesting things when it comes to actually discussing a new mechanic or stage of a game, because even though you are all on the same page chatting. All member can walk away with a different image of a rocket or monster in their heads. With documentation and solid references, you can bring everyone’s vision together to work on a common goal.
  • Answers Questions: I do not need to explain this in much detail. If people have questions and do not know who to ask, they then can find the information they seek within the documents.
  • Brings new members up to date: It is more than likely you will have more members or new devs joining your team. With this in mind, they will have a lot of questions and pre-conceived notions of what the game may be about or how it will play. Now with documentation, you can give them a chance to understand the project but also give you a fresh perspective on the game. This works for both new members but also your game as they may have a better idea or see an issue with the current method.   
  • Great starting point: Documentation is a good way to test and show your ideas to others (prototyping overall is often the best idea) Most games start with an idea and then a design document which is great for receiving feedback and testing ideas.

Those are some valuable reasons on why documentation is important, but documentation comes in all shapes and forms. Remember this because this is very important when communicating with all the other teams.

In games development, there are many disciplines which come together to create games, Art, Animation, Game Design, Level Design, QA, and much more. Each of these groups can read but all prefer to communicate in other ways. For example, me sending two pages of text would work better with the Story team instead of the art team. Because (and I am not lying here as I have been in situations when sending bullet point docs to Art members) the art team would prefer pictures and would understand what I am looking for more with references instead of a detailed description (a picture speaks a thousand words). Which leads me on to discussing how to create your documentation.

When creating documentation think about who is going to see this. Is it going globally or just a specific team or the set number of people across disciplines. Once you know this you can start to tailor your document to your audience to have the best impact. If you are speaking to directors, normally it is best to keep everything at a high level, yet in a review situation then you should reveal more details to them.

All of these topics should enter your mind when you are creating these documents:

  • Who is it for?
  • How many disciplines will see this?
  • Should it be a high or low level of details?
  • Can pictures/diagrams show my point better than words?   
  • What is the main message you want to communicate?

Once you know the answer to these you can then start to plan accordingly, and make it sexy. It is very important,  to make it eye catching, seriously when your documents go out you need to make sure it hooks people. In games we get a lot of emails a day, each wanting a lot of attention so make sure yours has everyone! Just black text on a white background will not pull readers in. I know it is just a document and I am sure it has some great information, but you need to show it in a cool way that makes the reader want to learn more.

So there we have it, team, I hope this made you think a tad differently about documentation, and why it is important when it comes to making games. It is really is helpful on many levels and for a multitude of reasons. 

Remember moving forward that you should take creating documents serious because these can be the start of something special when it comes to designing your game. Make it look and feel as important as your game as this is how you will get other team members inspired as well as interested in your work.

If you want to chat hit me up on Twitter: @MaxPears



Latest Jobs

IO Interactive

Hybrid (Malmö, Sweden)
Gameplay Director (Project Fantasy)

Arizona State University

Los Angeles, CA, USA
Assistant Professor of XR Technologies

IO Interactive

Hybrid (Copenhagen, Denmark)
Animation Tech Programmer

Purdue University

West Lafayette, IN, USA
Assistant Professor in Game Design and Development
More Jobs   


Explore the
Advertise with
Follow us

Game Developer Job Board

Game Developer


Explore the

Game Developer Job Board

Browse open positions across the game industry or recruit new talent for your studio

Advertise with

Game Developer

Engage game professionals and drive sales using an array of Game Developer media solutions to meet your objectives.

Learn More
Follow us


Follow us @gamedevdotcom to stay up-to-date with the latest news & insider information about events & more