Clean Design Documentation Principles
Hello everyone. Previously, I wrote an article about clean game design principles, which are quite abstract. Now I want to tell you about principles which can help you to improve the quality of your game design documentation.
The second most common question I’ve heard from beginners was “How to write a superb game design document?”. It’s challenging to answer just because different teams and designers have different approaches how to write design documentation. Moreover, beginners tend to make similar mistakes while working on game design documentation. One moment, I started pondering how to establish basic rules of writing documentation for beginners without teaching them a particular approach.
And yet again, programming helped me to find the answer. “Programmer spend more time reading the code than writing it” is true for game designers as well, but in different form “Game developers spend more time reading design documentation rather than writing it”. It’s vital to write a high-quality design documents which are easy to read and understand in short time by various people in the team. Eventually, I derived a list of clean design documentation principles.
Let me introduce them:
- DSP. Documentation Segregation Principle;
- SRP. Single Responsibility Principle;
- OCP. Open Closed Principle;
- KISS. Keep It Simple, Stupid;
- DRY. Don’t Repeat Yourself;
- PCP. Practice Consistency Principle;
DSP
Documentation Segregation Principle.
This principle states that it’s better to have several small documents instead of a huge one. To put it bluntly, a game design document is a collection of many tiny design documents which describe individual mechanics and systems aka wiki “What we want in our game”.
Regardless if you have a tiny or large team, nobody needs all the information to make a small portion of a game. Thus, developers are always focused only on a small part of a project, which is the task at hand. And a tiny document which focuses on a particular system or mechanics is better because it contains only necessary information about an absolutely different part of a game. Additionally, people will spend less time reading concise documents, and the probability of misunderstanding some information in it will be lower.
Moreover, this principle facilitates the process of collaborative work. Usually, there are several game designers in a team, even in a small one. As a result, there will be a lot of changes in documentation during the development process. And DSP will decrease the chance of mistakes which can lead to spoiling somebodies work.
Lastly, it’s more trivial and just quicker to make changes and find errors in a small dedicated document than in a large one.
SRP
Single Responsibility Principle.
This principle states that each individual document should describe only one individual mechanic/system or aspect of the game.
Following SRP gives you two major advantages. If you describe only one aspect of a game (e.g. a monster, weapon system, progression, player’s ability, etc.) at a time, you will keep your mind focused and write a document quicker. As a result, documentation becomes concise and easier to read. Consequently, it’s more simple to find and fix errors; and teammates spend less time reading it and the probability of misunderstanding and miscommunication is much lower.
However, SRP is a tricky principle. You can easily turn your documentation into a disaster if you follow it to the letter. Avoid creating separate documents for miniscule parts of a game. It’s good to have a document describing a boss fight. But it’s horrible to create separate documents about behavior, each ability, an arena, etc. In this case, it’ll be extremely hard to put all pieces together and get a holistic vision.
OCP
Open-closed principle.
This principle states that everyone can comment on the design documentation, but only the author can make changes to it.
Indeed getting feedback on your documentation is a vital process. Not only does it provide a different point of view but it also can point at some mistakes in your writing style and the document structure. However, it’s an absolutely dull idea to give everyone to change your documentation, as it leads to two major problems.
First, you can’t establish a person who is responsible for the document and can answer questions about some details. If everyone is responsible, nobody is.
Second, ninja changes, which you’re not aware of. Even if your team has an agreement about such amendments, it doesn’t protect you from simple human mistakes. I admit, in some rare occasions some little changes may be added, for instance, during the author’s holiday. Of course, the author must be informed about these changes.
Not only does OCP help to avoid such troubles, but it also helps to establish a strong basis for sharing feedback in a team.
KISS
Keep It Simple, Stupid.
This principle states that it’s better to use relatively simple language for the documentation to avoid ambiguity and possible misunderstandings.
Usually, beginners tend to write large and sophisticated texts, just because they think the bigger the document the better it is. It’s a common misconception. Don’t evaluate the quality of design documents relying on their size, do it relying on how informative they are.
As I have already said, the design documentation people read more than write. Using some sophisticated wordplay, idioms and rare words will make your texts harder to read and understand. Remember, writing documentation isn’t a literature competition, it’s a way to convey design ideas to the team.
The problem is that any game development team has a lot of different people with various backgrounds. In addition, during the development process, each member of a team consumes humongous volumes of information, eventually, they can make some mistakes and understand some parts of a document differently. That’s why it’s essential to use simple language which is straightforward and hard to interpret wrongly. Simple texts are quicker to read and are better for skimming, because time is a vital resource which everyone must spend wisely during game development.
Notably, it’s quite trivial to overuse this principle. And ultimately your documents become quite challenging to read as you’ll use so simple language that you’ll start explaining many things using a lot of words.
DRY
Don’t Repeat Yourself.
In software development, this principle states that every piece of knowledge must have a single, unambiguous, authoritative representation within a system. In our case, I prefer to slightly rephrase it into “Every reused mechanic or system must have a single, unambiguous representation in documentation”.
This principle is needed to avoid ambiguity and unnecessary information duplication. It’s fairly common for beginner game designers to describe one thing several times in different documents. Consequently, it’s fairly easy to get to the point when you have several documents which contradict each other because the game designer hasn’t updated duplicated parts.
That’s why I strongly recommend writing a separate document for a mechanic/system which you will use in other mechanics/systems. Not only will it be easier to make changes just because it’s one document instead of several, but it also will decrease the amount of text you must write. Mostly because you can give a link on a document with a short comment instead of describing everything yet again from scratch.
PCP
Practice Consistency Principle.
This principle states that documentation must have a consistent style and structure across all documents.
To achieve this I highly recommend preparing some game documentation guides in which you must describe the most common structure, for your documents and some basic rules about additional files like video, images, schemes, and flowcharts.
First of all, it will help you to write documentation faster just because you’ll have really good instructions on how to write documents for your project. As a result, you’ll spend less time thinking about how to organize yet another document. In addition, it helps with blank page syndrome, because you always can start creating the common sections.
Second, it’s really easier to read different documents when they have a very similar structure, just because of how our brains work. Moreover, it will help to avoid misunderstandings and dramatically improve the speed and quality of searching particular information in the documentation.
Conclusion
You must remember, that these principles are general recommendations, not a list of strict rules.
Don’t use them religiously, as it can make everything worse. There are exceptions, when all these principles work extremely bad, for instance, when you work on a minuscule game like a hyper-casual game (in terms of the amount of mechanics).
Everything is good in moderation. As I mentioned before, if you will follow each of the principles to the letter, you will definitely spoil your documentation. However, the only way to learn to write excellent documents is through practice, because only practice makes perfect. But I strongly recommend asking for feedback from peers or more experienced people. Without good criticism, you won’t find how you can improve your documentation style and avoid some common mistakes in the future.
