10 universal tips for making game design documentation
Clear documentation is essential to make sure everyone is on the same page. From including version control to making things as visual as possible, here are the critical guidelines to follow.
This may upset some to hear, but the fact is, game designers spend most of their working time documenting the project, rather than actually creating games. This is a necessity in order to facilitate solid team communication and to create a sort of “collective memory”. So, on that note, when writing documentation, you should always keep two questions in mind.
- Who are we writing for?
- What do we want to tell the reader?
First of all, as mentioned, you need to figure out who is going to read your documentation. To answer this question, let’s consider a simplified diagram that illustrates the process of transferring information between specialists within a team.
Besides compiling documents for different departments, designers also participate in the document flow between departments. Obviously, artists, managers, and programmers need completely different documents that serve different purposes.
Is there one template out there that works for everyone? Yes. But in practice, such a template is huge, inconvenient to read, and difficult to keep up to date.
Therefore, a game designer will often write separate documents for individual project features and adapt them to the specialists who will directly work with it.
This means that instead of looking for an ideal template (which doesn’t exist), it’s better to focus on some general rules for entering project data into a single base of knowledge. Here are some key rules:
- document storage should be done in a logical way
- all project documents should always be available to all team members
- a game designer must ensure that the content is up to date
- all texts must be written in an informational style that eliminates discrepancies
- the project description must be complete and logical, but not redundant
- all documents should use uniform terminology
- links to other documents with information that isn’t directly related to the feature, but may be needed by colleagues, should be inserted in relevant places
Document design tips
In a nutshell: everything that can be expressed in a format other than text should be expressed that way.
It’s often difficult for a novice designer to choose good methods for document design or techniques for expressing thoughts. In fact, you can identify a poorly written document without even reading it.
If you’ve got a wall of text like the one on the left, here are some tips for turning it into a structured, easy-to-read document; these tips are universal and suitable for any document.
1. Add version control
Use: tracking changes made to a document.
Includes:
- a version number
- date of changes
- what changed
- who made the edits
Example:
2. Include a short description
Use: allows a specialist reading the document to quickly figure out if it contains the information they’re interested in.
Includes: general information about the contents of the document, described in two or three sentences. May contain links to internal sections or to other documents.
Example:
The fishing rod is a tool designed for catching fish and objects from bodies of water.
A fishing rod can be used via the “Tool” button. If the fishing rod isn’t in the hero’s hands, then it’s stored in their inventory or on the quick access panel.
To use a tool, you must assign it a sensor with customizable range parameters.
3. Make the goal clear
Use: this answers the question: “Why are we doing this?” It helps the author remember the problem they’re solving, and helps managers determine implementation priority.
Example:
- increase APRDAU by 10% due to the introduction of the event
- add the ability to customize characters with the subsequent introduction of paid content
4. Include a table of contents
Use: quick navigation within the document. The document text should consist of sections, formatted by headings.
Includes: hyperlinks to the different sections of the document.
5. Use lists
Use: organizing similar elements and giving them additional highlighting in the text.
Rules:
- items must be marked
- list elements must be homogeneous
- numbered lists are used to rank or describe the order of actions
- if there are many sublists, it’s better to express this information in a table
6. Include mockups and references
Use: show what the described object will look like in the game, where it will be located on the screen, and how it will be used. This helps reduce the number of discussions and edits.
So, how do you know that you need a mockup? Everything that requires visual representation should be supported with references.
Examples of references:
- a screenshot from another game
- a GIF of mechanics
- a hand-drawn sketch
- and so on
Examples:
The picture below shows sketches with three options for a character’s emotions. This mockup was made using simple graphic tools on top of a screenshot from the game.
It’s better to use a GIF to describe emotions and VFX.
Feel free to use simple hand drawings and photo collages. The main thing is to convey your idea, and the specialists will implement it in the optimal way.
7. Provide a UI description
Use: the artists will have a much easier time drawing interface elements if they understand how the window is supposed to work. Additionally, it’s more convenient for developers to implement functions if they know in advance the windows where specific elements will be located. The following format will help bring the technical and artistic description together.
Includes:
- a schematic drawing of the future interface
- a description of the functions and states of the elements
- number and size of texts in the window.
Example:
8. Use infographics
Use: infographics perfectly complement system descriptions; specialists will quickly understand the composition of a structure and how its elements interact with each other.
A diagram is perfect if you need to describe:
- a cycle
- a change of states
- interacting objects
Examples:
- Core-loop of the game
- Interface interaction
9. Block diagram
Use: to describe action algorithms and complex systems.
Includes: individual steps described in the form of blocks connected by lines and conditional blocks. There’s no need to draw up complete diagrams in accordance with state standards — the main thing is that the diagram should be clear and readable.
Examples:
Let’s say that there are design errors in the matchmaking algorithm design — have a visual diagram will greatly aid in conversations about fixing it:
10. Leverage graphs
Use: people find it difficult to quickly comprehend large arrays of numbers, so it’s worth using graphs and diagrams to visualize them.
Rules:
- select a type of graph suitable for the purpose of data analysis
- don’t forget the names and labels of the axes
- use the minimum details and visual effects
Let’s sum up what we’ve discussed. Documentation allows us to competently and clearly convey the game designer‘s idea to the rest of the team. Without them, communication will be disrupted, and the work process will become chaotic. Further, the game designer should try to convey their idea as clearly and unambiguously as possible, so you should always remember a few simple rules:
- remember who the reader is
- remember the purpose of the document
- if you see text in a document, try to present this data visually
What else to read about game design:
