Common Game Design Documents

in

In a recent twitter thread, I posted a general challenge to professional game designers to share more of their game design documentation. The goal: give academia more examples to learn from. I’d better put my money where my mouth is!

But first, I wanted to share some general thoughts about project documentation, and examples of common documentation archetypes.

The Monolithic Game Design Document (GDD)

When I was in school my professors spent a lot of time teaching how to write formal game design documents (GDDs), stressing their importance. These were single monolithic documents that supposedly captured every detail of a game’s design. In theory the entire team would read the GDD, refer to it often, and trust it to have any answer they might need. They would set and communicate both creative and art direction!

GDDs are a tidy fantasy: they imply that you can sit down and design a whole game at the beginning, that a game’s design is an artifact that exists separately from implementation, and that once the document is finished the design is finished. But none of that is ever true, and GDDs do more harm than good. They are a lot of work to write, they centralize too much decision-making power in inflexible ways, they are nearly impossible to maintain, and nobody ever reads them.

Purpose-driven Documents

Instead of monolithic GDDs, documents should be concise and serve specific, narrow goals. When writing documentation, I advise asking yourself:

  • What is the goal?
  • Who is the audience?
  • Does it need to be maintained over time?
  • Will it be an authoritative “source of truth”?
  • What is its lifespan (IE, when does it stop being maintained or authoritative)?

If you don’t have answers to those questions, then you will not write a useful document.

All documentation should be as concise as it can be and still achieve your goals. Your audience’s time and attention span are precious resources.

Common types of documentation:

Every team has different conventions for documentation, and may have wildly different names for the same kinds of document. But there are common patterns. Below are examples of documents that game designers may need to write or review.

Project Documentation

DocumentDescription
Pitch A document used to help convince decision-makers to agree to something.

Usually very short, ~1 page, often contains evocative imagery.

Audience:
Project Leads.
Stakeholders who might be affected.

Maintained:
No
Feature SpecA “specification” document that describes a feature at a high level, and defines requirements or goals. Commonly used by someone who will NOT be implementing a feature to describe it to someone who will be, or written by the person who WILL be implementing it to get feedback or oversight from their leads or stakeholders.

May also be used by test to help write their test plans.

Audience:
Implementers
QA
Leads/Stakeholders

Maintained:
Maybe. It is often only maintained for a short while; once implementation starts direction may shift to other formats.
Content Reference SpecA “specification” document that describes every element in a set of content, often in detail.

For example: a list of all the missions in a campaign, or the written design for every special ability for a champion in a MOBA.

Audience:
Implementers.
QA.

Maintained:
Yes. Must be maintained to be useful, but you can often retire these documents once their content has all been stubbed out or created, at which points the actual game data can replace the documentation.
Best PracticesA document that describes design or content conventions. See “Enforcing Content Conventions”.

Audience:
Anyone who implements the kind of content that these practice apply to.
QA.

Maintained:
Yes
AnalysisA document that exists to gain insights from existing data or content. Perhaps you have the stats for all your characters in a spreadsheet and formulas that help you extrapolate or review the impact of those states. Usually spreadsheets.

Audience:
Anyone who needs to make decisions based on this existing data.
The design team for this kind of content.
QA.

Maintained:
Maybe. Sometimes maintained as a permanent resource for a design team.
Test PlanUsually written by the QA team, a test plan is an exhaustive checklist of tests to run against a given feature or piece of content.

Designers may be involved in brainstorming or reviewing these cases, and on some teams may be involved performing the tests.


Audience:
QA

Maintained:
Maybe. They may be single-use, run multiples times, or re-used over and over as part of a pipeline.

Workflow or Tool Documentation

DocumentDescription
Bootcamp/TrainingA document describing a training exercise with a large series of steps, with the intent to build up practice and understanding of a tool or workflow.

Audience:
Anyone learning the described tool or workflow for the first time.

Maintained:
Yes
How-ToA document that describes how to achieve a specific goal within the tools or workflows used by the team.

Audience:
Anyone who uses that tool or workflow.
QA, for whitebox testing.

Maintained:
Yes
Technical ReferenceA document that describes in detail all the elements or options within a technical system. For example, it might list all the script functions available for a specific type of object, or all of the possible properties and their values that can be set in a specific type of file.

Audience:
Anyone who uses hat tool or workflow.
QA, for whitebox testing.

Maintained:
Yes

Temporary Documents

DocumentDescription
Working DocsSometimes you just need a scratchpad or temporary spreadsheet to scribble notes or do quick and dirty calculations with.

Maybe it’s for brainstorming, outlining, organizing your thoughts, or double-checking that things line up how you thought.

Audience:
Yourself

Maintained:
No
Meeting NotesEvery meeting should have results (otherwise why have it?), and if the results are relevant to anyone outside of the meeting, or relevant in the future, then you should write them down!

Effective meeting notes are usually short and sparse; capturing only what needs to be captured. The job of meeting notes s usually short-term communication. Anything that needs to be preserved longer-term probably needs to be converted into another, more maintained format.

Audience:
Specific people or stakeholders who need to be in the loop on the meeting’s results, or who are responsible for action items coming out of the meeting.

Maintained:
No