A simple format to archive design decisions

This article written during Nanotale’s development describes how we kept an archive of decision-making within the design documentation with the help of a few simple icons.

Before starting production on Nanotale, we took some time to prototype various typing gameplay ideas. When prototyping, you have to focus on the things you want to test, and iterate on them as fast as possible. There is no time to document everything. But the prototypes do not always speak by themselves. (Sometimes there is no playable build to keep, like the time I tested interactive dialogs by acting as the NPC and talking through Slack with a colleague. We will get back to that.) So we needed a way to archive what we learned from each iteration, in a format that would be quick to write and read.

The Problem

This is a common problem of design documentation. How to keep an account of the decisions that led to a design as it is? It is interesting to keep a trace of previous iterations, to look back at the evolution of a design. But more importantly, it is a waste of time if another designer (or your forgetful self) makes changes that recreate a problem that has already been solved, just because they have no knowledge of the history behind that decision.

For all those reasons, I was looking for a practical way to link each feature to the decision path that led to it. It needed to be quick to write and to read, because if we have to go back and read multiple paragraphs of history, we all know no one will do it. Surely, someone already came up with a solution, right?

A Solution

Sadly, I could not find anything related to game design. The results I found were tools to keep track of programming design decisions in code, as it seems programmers need a similar solution for similar reasons. Eventually, I found a research paper about an experimental tool made to present design decision-making in a simple way. It gathers “decision elements” from different sources (code annotations, designers’ UML diagrams…) and organizes them visually in a hierarchy, like bullet points. If you want to know more about the technical details of their tool, it is called “DecDoc: A Tool for Documenting Design Decisions Collaboratively and Incrementally” (Hesse, Tom-Michael & Kuehlwein, Arthur & Roehm, Tobias 30-37. 10.1109/MARCH.2016.9)

I took inspiration from their bullet points presentation. It is brief, the icons convey a meaning that does not have to go through text. When taking notes, only a few words are necessary. It is great for what we want. Here is a made up example of what it can look like for game design:

  • ! We need X to give game experience Y
    • ✔️ There are no other games doing X
    • ⚠️ An aspect of X can be too costly
      • key X can be limited to a few occurrences
      • key We can try the different way Z instead
      • ➤ Give Z a test to decide
    • ? How does this affect W?

And here is a real example form the prototype of the dialogue system I was alluding to in the introduction. To give a bit of context, it was a test for a typing based branching dialog. Typing highlighted keywords would make the conversion go forward on the topic of the chosen keyword. The playtest challenged the idea of having secret keywords the player could type by himself, that they would have learned from another NPC.

Our Version

We took a few generic icon types from the original source and added others as they were needed. Here is the full list of the icons we have:

! PostulateLet’s admit that…
👉 AssessmentWe already know that…
? QuestionUncertainty to be resolved or defined
X ProblemCreates a problem / inconsistency
⚠️ RiskMay not be fun / doable
flag Red FlagProblem will probably come up later on
⊕ IntentionMotive behind a decision or design
star OpportunityGood thing that can be developed
key SolutionProposition of a solution
lightbulb IdeaProposition of an additional feature
✔️ Argument forArgument in favor of
❌ Argument againstArgument against
note NoteAdditional information
➤ DecisionFinal decision of what we are doing

All the icons are basic unicode emojis and not images to gain time and ensure full compatibility. The bullet point notes of each prototype where copy pasted into Slack for the whole studio, and you can now see an example in this article, without extra work. They can also all be drawn quickly, at least in broad strokes, to be used when taking notes with pen and paper.

Extended Use

When we entered into production and decided to use a wiki as our design document, we ported the icon system to it. The wiki tool that is made to convert => into ⇒ was modified to change :idea: into 💡. Here is another example, taken from the wiki page about the consumption of “mana” to cast spells.

We ended up using those icons to add quick “work in progress” notes in our design documents. The most common is the idea icon (💡), used whenever we want to add an idea to an existing page for later review. The couple problem (🛑) – solution (🔑) identifies problems and solutions to evaluate whenever we can take the time to redesign the feature. The intention icon (⊕) has been added later, specifically for the wiki, to justify the purpose of a feature.

Game design documents are in a constant work in progress state, evolving during development. They are often out-of-date from the latest changes if you do not have someone dedicated to that (which, on our small team, we don’t). The tool and format we use to write them should support that. With our system, whenever we see a bullet point with an icon, we know that the information is still part of an ongoing discussion. Other team members can trust what is written because what is unknown or unsure is also documented. The design process is transparent in the documents.

In the future, that system will evolve a bit like a new language. In one hand by adding the icons we need, and in the other hand by removing the ones that are not used to avoid cluttering. The list as it is now is probably a bit too long. Now that I have told you everything, I would love to know if that system can be useful to others, or if other solutions exist.