Jump to content

  • Log In with Google      Sign In   
  • Create Account

Like
28Likes
Dislike

Documentation for Indie Studios: Why do you need it?

By Ivan Spasov | Published Aug 09 2013 09:11 PM in Game Design
Peer Reviewed by (Gaiiden, Orymus3, Sik_the_hedgehog)

design documentation technical indie

I've asked myself a lot of times a simple question - Why do so many indie studios start a project, go midway with it and the all of a sudden, they close it? It just seems that things tend to fall apart for these projects. But where did it all go wrong? The answer here is simple - the basics were messed up at some point. The game ended up being built with a base and groundwork that can't support the features intended for the end result. Also, quite a lot of times, the base of the game just ends up causing bugs and havoc in your own project. While the reasons for this can be many, one is nearly always there - these projects were all missing good documentation.

This happens mostly due to the fact that a lot of indie studios are built from guys and girls, who already have a day job and they are doing this just for the love of making games. They (especially the developers) tend to write a lot of documentation at their work place and the last thing that they want is to do this all over again in their "pleasure" time.

Also a strong factor here is that a lot of indie studios don't have a team that is well split up into groups. A lot of the times, you don't get to have a Game Designer, Developers, Designers and Animators. Most of the times, you have (for example) two or three developers, one of which plays the role of the game designer as well, then you have your 3D artist, who does the animations, works with the textures and the 2D and UI design and by some chance out of this entire team, you have a person that knows a little something on sound, so he/she does this as well. There is nothing wrong with that - this way you are all on the same side, you all know what the product is going to be like, you all gain new skills/perspectives and it's all good.

Good Documentation is a Must


In the introduction, I've pretty much given a good example of what could go wrong if you don't have good documentation. However, let's take a look at what could "go right" and in the end - benefit the entire team:
  • You get the chance to map out your ideas and analyze them as time goes by.
  • Everyone knows what's going on with the project.
  • Getting someone up to speed with what you’re doing with the project.
  • Keeping the development consistent.
  • Keeping track of the code. This is very useful for a future refactoring process.
  • Getting an overview of the main points of your concept and the way that you implement them.
These all sound like nice features, right?

There is a point to be made here – a lot of game designers and producers neglect the documentation to a huge extent. Generally speaking, most non-developers tend to neglect it. This is really going to become a problem when your ideas start to water down and you don’t have your previous ideas written down. You really need something to revert to in order to see if your current idea is consistent/good or applicable at all.

So what does a good documentation consist of?

Let’s take a look at this list:
  • Project Blueprint
  • Design Documentation
  • Technical Documentation
  • Workflow Documentation
  • Version Documentation
Now we have to look at what these are and how/when to implement them so they can serve their use.

Documentation How-To


The process of writing down your documentation has to start after your first brainstorming or whatever it is that the individual indie studio does to get their concept together.

Enter the Blueprint – the project blueprint is something really, really important. It’s not supposed to be a several hundred pages long book – it’s supposed to be a blueprint. That means that in it, you have to write down only basic things and map out what you are going to do as a base idea and what you are going to build upon. This would include:
  • Basic story – don’t get into writing storyboards. Just map out that in your game, for example, a guy will be slaying dragons, obtaining items and saving damsels.
  • Basic gameplay features – again, no details. You don’t need to have the complete rule set or high-end concept. Try to put in perspective the genre of your game, the most basic concepts of the gameplay aspect and some ground rules. To build upon the example from the previous paragraph, you should put in your blueprint that you are going to have a 3rd person hack’n’ slash game, where you will have three playable classes, you will have bosses, mobs and you will gather items and level up.
  • Target groups – this one is very important. You need to map out your audience and also, the platform you are going to build this game for. That’s not to say that you are going to include numbers here or go out of your way to do deep research. Just something like this (again, applicable for the example above) – target is RPG fans, the platform is PC.
  • Basic technical specs – this is really the meat of your document. Here you should write down what you are going to use to develop the game. You are going to choose your programming language, your game engine (if you are planning on using such and not go too low-level), your database, probable server connections, software tools (for the 2D/3D arts and sound) and so on and so forth. Here you do not need to write code specifications. Just map out the technologies that you are going to use.
  • Estimations – this one is not to be taken lightly. It’s essential that your work is traced by your own project estimations. And by estimations here, I’m not talking so much in time, as this is something that simply can’t be really estimated, but more in terms of resources. You need to estimate what kind of resource is going to go into what you are about to do. Are you going to purchase some software, or are you planning to go Open Source? How are you going to match your development process? Are there some additional things that need to be included into the estimate? Those are the things you really need to worry about.
  • Other groundwork stuff – on a game-to-game basis, this may vary or not exist as a paragraph all together. However, some games have very specific needs. If such a thing is going on with your idea, you better write it down.
So how do we go on from here ?

Well, first of all, we have to build up stages of development. That alone is a document right there. Each development process has to have phases. Building the base of the game, then adding functionalities, then adding higher detail, then pushing emphasis on certain high-end features and so on and so forth. This is all to0 general, so I’ll give an example:
  • First stage – building core mechanics on a test stage/level/whatever. Here you will build up the core mechanics and have something to upgrade and build on, in order to make a better product in the future.
  • Second stage – refine mechanics from first stage and start to add features.
That’s kind of the way you would need to go about with this. After planning as much stages as you need, you eventually would get a stage with polishes, working game fragments and in this way, you will be able to get down with the final version of your product.

This is the part where it gets more complex.

In each of these stages, the Game Design documentation has to flow into the Technical Documentation. That’s to say that the Game Design documentation has to play the role of a task giver for the technical part. The things that you would have written down there have to be developed. To be developed, they pass through the technical documentation as a first base.

The Game Design documentation should contain the features that you would want to be developed. This means all of the gameplay features per development stage should be written down here. They should be detailed as much as possible, depending on the development stage. It is key to note all of your features in this document, as this is the guideline for the developers’ tasks ahead.

When writing this down you must have a clear idea with depth. If at some point you decide that this is not the way you want to handle things, you are just going to throw in additional and basically wasted work. Write down only the features that you are sure about. The ones that you still don’t see clear enough – leave them be for now. It’s better to plan this out before someone actually starts to work on it.

After the Game Design documentation is done, the Technical Documentation goes into play.

You map out the features from the game design and start to put them into programming perspective. You lay out the tasks in front of you and from here on out you start to think about actual coding. In the Technical Documentation you should map out your future tasks and their realization only as far as class and interface logic goes. That’s to say you don’t put actual code in there. You prepare the interfaces that are going to be implemented and think out their functionality. Then you think of the classes that are going to be into play, either implementing the interfaces or going for new functionalities all together. You think of Design Pattern usage, overall algorithms and so on. From there the developer will know how to build it into working code.

Now that that’s done, you should think of the Workflow Documentation – it is comprised of the development parts that need to be put together. To talk with examples – let’s say you have a 3D designer and a developer. You have to map out the activities of each of them and see where they cross paths. That’s to say that you should strive to put the people’s effort into doing a start-to-finish kind of thing on their tasks. The developer starts to work on character movement – he has to have a model to do that to. Yes, sure he can work on that with just a basic box … but that’s just not a good practice. At all. You need to get your resources ready at the right time. That’s where you need to map out the activities - the 3D designer should be ready with the basic model and animation by the time the developer gets around to doing the player movement.

And last but not least, the Version Documentation. This one is very critical – write down what you change with each version. That way, if something goes extremely wrong, you will know when it happened and might be able to see what caused it.

However, a strong point here is that this documentation should be kept short and should have a list format. You should not include source code in this or anything technical for that matter. It becomes hard to read and bad for problem detection.

Interesting Points


Some things to look out for when writing this type of documentation:
  • You are a specialist at your field, be it developer, game designer and so on. Don’t become a documentation fiend. You should keep your documentation writing at the low end. Write the most important things and things that have strong dependencies. Don’t waste time.
  • Do not include personal thoughts in plain text in your documentation – this is work, not the fantasy universe of Lord of the Rings.
  • Keep in mind, this is internal documentation for use within the team. High level of professional and business talk only wastes your time and that of your colleagues. Go straight to the point.
  • No need for tables and graphs. Period.

Conclusion


Documenting what you and your team are doing is something very important. It can save a lot of time in development and increase efficiency to a new level. However, documentation alone does not guarantee success. It cannot replace good technical expertise or the willingness go get such. It cannot compensate for lackluster design and bad code. It cannot make your story better or your code more readable.

If you truly want your product to succeed, be creative and at any level (beginner, intermediate, advanced etc.) try to be up to par with the best practice guides.

Article Update Log


02.05.2013 – The article was first written.



About the Author(s)


My name is Ivan Spasov and I'm a game developer.
I'm working in the gaming industry but I've had my share of experience in the corporate business development world as well.


License


GDOL (Gamedev.net Open License)




Comments

It is a nice article, and I think an important one for aspiring indie teams.

 

I have two suggestions:

With the text "– leave them be for now. It’s better to plan this out before someone actually starts to work on it.


After the Game Design documentation is done, the Technical Documentation goes into play.", an inexperienced developer might think you are propagating a Waterfall Strategy. I am very sure this wasn't your intention, or a version doc would not make sense. Waterfall seems to be the bane of programming, especially younger developers are still trying to work this way. Could you make it clear somewhere?

 

The second suggestion is about the paragraph after "... the Technical Documentation goes into play", you are basically talking about software design and what a software designer should specify. I think this is impossible to cover in one paragraph. I agree, the most important things to document are the interfaces, or else the code of team members Alice and Bob won't work together. But the interface of what, where do you draw the line? Sometimes, if the developers have split up working in different "modules", it is enough to specify the interfaces they offer and the responsibilities they have. Leaving the actual classes with the implementation to the developer. 

I also think that, in general, a software designer should not need to specify the algorithms to use, that is an implementation detail of the class/module. If the interface needs to know about the algo, you should probably rethink the design.

 

In short, I think the paragraph hides the powerful choices you have in the early software drafts. If you tell a young developer to plan out the classes and interfaces, he or she tends to make huge decicions without even realizing that he/she had a choice. There are good reasons for a designer to accurately specify some classes, but there are also good reasons to leave whole project parts undefined.


Note: Please offer only positive, constructive comments - we are looking to promote a positive atmosphere where collaboration is valued above all else.




PARTNERS