Jump to content
  • Advertisement
  • 02/03/19 12:03 PM

    A Simple Format to Archive Design Decisions

    Game Design


    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
        • 🔑 can be limited to a few occurrences
        • 🔑 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 conversation 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:


    ☝️ Postulate

    Let's admit that…


    👉 Assessment

    We already know that…



    Uncertainty to be resolved or define


    🛑 Problem

    This is / creates a problem / inconsistency


    ⚠️ Risk

    This seems risky and may not be fun/doable


    🚩 Flag

    This problem will probably come up later on


    ⊕ Intention

    The motive behind a decision or design



    A good thing that can be developed


    🔑 Solution

    Proposition of a solution


    💡 Idea

    Proposition of an additional feature


    ✔️ Argument for

    Argument in favor of


     Argument against

    Argument against


    ✏️ Note

    Additional information



    Final 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 also 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. On 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.

    Thank you for reading. 

      Report Article

    User Feedback

    Thanks for sharing, seems like a good approach, and very easy to work with! :)

    Have you also read Daniel Cook's description of "Game Design Logs"?

    Share this comment

    Link to comment
    Share on other sites

    I like to use Freemind for such stuff. It has the advantage that is dynamic so nodes can be folded/unfolded to keep the information clear. If something new comes around for a specific topic you can just add a child node for this specific topic node to add detail information (for example problems, thoughts, decisions and more). Detail info is then folded away to not clutter the main information. If somebody comes around he can look at the child nodes to see if there is something important. I also attach icons to the nodes if they are of specific importance. Last but not least you can link nodes. Allows to create node groups about a specific topic leading straight to the actual text nodes with the in-detail explanations. I've seen no better tool so far to organize simple to complex project information without turning into a clutter-festival.

    Share this comment

    Link to comment
    Share on other sites

    @jbadams No, I didn't. Thank you very much for sharing. 

    @RPTD That's another way to do it. Doesn't it become too messy at some point using a mindmap? 

    Share this comment

    Link to comment
    Share on other sites
    8 hours ago, FishingCactus said:

    @jbadams No, I didn't. Thank you very much for sharing. 

    @RPTD That's another way to do it. Doesn't it become too messy at some point using a mindmap? 

    Personally I don't think so. It depends on how you organize it.

    The strength of Freemind is that you can keep all the detail stuff collapsed until you really need it. So if new info comes by you can really attach it to the place where it belongs (adding detail info). It's there while not cluttering which I find a great help.

    Furthermore the linking helps a lot to keep information tidy while finding it which I find very difficult with linear design docs. It does not matter where somebody thinks a certain detail info is attached to best (often more than one place) because at the other places you can just add a link to it. In my case for example I use to have detail info on character abilities underneath the character. If there is for example a scene/task/plot-point where I want to focus on such an ability I can plop in a node pointing to the root node describing the ability in detail. So if somebody comes by this scene/task/plot-point and sees this link and wants to read the additional info (or add important info himself) he can just straight jump to it without needing to know where the info is located nor having debates about where it should be.

    I think important with Freemind and Co. is also to have a "links" node which contains child nodes linking to important places. This way you can keep the majority of nodes collapsed, keep the important parts visible, and still quickly locate and update the info you need.

    As with all tools people need to apply a certain level of discipline. For example to not make more than 10-20 child nodes and grouping them if they get too numerous. If used the right way I think it's a great help especially in contrary to linear design documents.

    Share this comment

    Link to comment
    Share on other sites

    Create an account or sign in to comment

    You need to be a member in order to leave a comment

    Create an account

    Sign up for a new account in our community. It's easy!

    Register a new account

    Sign in

    Already have an account? Sign in here.

    Sign In Now

  • Advertisement
  • Game Developer Survey


    We are looking for qualified game developers to participate in a 10-minute online survey. Qualified participants will be offered a $15 incentive for your time and insights. Click here to start!

    Take me to the survey!

  • Advertisement
  • Latest Featured Articles

  • Featured Blogs

  • Advertisement
  • Popular Now

  • Similar Content

    • By Pepsidog
      I'm wanting to create a hybrid game between turn based and action.  I'm looking to create a system where the player has a list of attack or move options on their turn, but I want to add a skill minigame in order to make the game more engaging for non-strategists.  I figured some sort of minigame or something.  Any ideas are welcome.  Thanks in advance!
    • By EchoCell
      Hello folks! I’m looking for advice on which engine I should go with for a 2D game I want to make. The goal is to make a side-scrolling beat’em up/2D fighting game hybrid where the main levels are in beat’em up mode, but the boss battles are in 2D fighter mode. The combat controls (combos, special moves, etc) would be the same in both modes, and the game would include a tournament mode that is entirely in 2D fighter mode.
      I have minimal game developing experience, and am essentially a noob. I am mostly familiar with RPGMaker, but have also experimented lightly with Unity. I have zero programming knowledge, and thus am partial to engines more accessible to complete beginners.
      What engine(s) would be best suited to this kind of game? I am interested in both M.U.G.E.N and OpenBOR, but I don’t think either would allow the kind of genre-crossing I want to accomplish without significant programming skills that I don’t have.
      Also - and I realize I’m thinking too far ahead - I would like to be able to release this game via HTML5 and just host it online somewhere if possible. Otherwise I am okay with it being PC only.
      Thank you for your time and input!
    • By mujina
      What could be a way of avoiding using inheritance and virtual methods when designing components for an entity-component-system?
      I'll be more specific about my design issue:
      I currently have different classes for different kinds of colliders (let's say, CircleCollider and LineCollider).
      My system that checks for collisions and updates the positions and/or velocities of my entities should be something like:
      for entity_i in alive_entities { collider_i = get_collider_of_entity(entity_i) // components of same kind are stored contiguously in separate arrays transform_i = get_transform_of_entity(entity_i) for entity_j in alive_entities { collider_j = get_collider_of_entity(entity_j) transform_j = get_transform_of_entity(entity_j) if check_collision(collider_i, collider_j) { update(transform_i) update(transform_j) } } } my problem is that I don't have a generic `get_collider_of_entity` function, but rather a function `get_circle_collider_of_entity` and a separate one `get_line_collider_of_entity`, and so on. (This happens because under the hood I am keeping a mapping (entity_id -> [transform_id, sprite_id, circle_collider_id, line_collider_id, ...]) that tells me whether an entity is using certain kinds of components and which are the indices of those components in the arrays containing the actual components instances. As you can see, each component class is corresponding to a unique index, namely the index position of the array of the mapping described above. For example, transforms are 0, sprites are 1, circle colliders are 2, line colliders are 3, and so on.)
      I am in need to write a system as the one in the snippet above. I can write several overloaded `check_collision` functions that implement the logic for collision detection between different kinds of geometric primitives, but my problem is that I am not sure how to obtain a generic `get_collider_of_entity` function. I would need something that would get me the collider of an entity, regardless of whether the entity has a circle collider, a line collider, a square collider, etc.
      One solution could be to write a function that checks whether in my internal entity_id -> [components_ids] mapping a certain entity has a collider at any of the indices that correspond to colliders. For example, say that the indices related to the collider classes are indices 10 to 20, then my function would do
      get_collider_of_entity (entity_id) { for comp_type_id in 10..20{ if mapping[entity_id][comp_type_id] not null { return components_arrays[comp_type_id][entity_id] } } return null } This could turn out to be pretty slow, since I have to do a small search for every collider of every entity. Also, it may not be straightforward to handle returned types here. (I'm working with C++, and the first solution - that is not involving inheritance in any way - would be returning a std::variant<CircleCollider, LineCollider, ... all kinds of components>, since I would need to return something that could be of different types).
      Another solution could be having some inheritance among components, e.g. all specific component classes inherit from a base Collider, and overrride some virtual `collide_with(const Collider& other)` method. Then I would redesign my mapping to probably reserve just one index for colliders, and then I would actual colliders in a polymorphic array of pointers to colliders, instead of having a separate array for CircleColliders, another for LineColliders, and so on. But this would destroy any attempt to be cache-friendly in my design, wouldn't it? That's why I am looking for alternatives.
      A third alternative would be to just have a single, only, Collider class. That would internally store the "actual type" ( aka what kind of collider it is ) with dynamic information (like an enum ColliderType). Then I would have all colliders have all members needed by any kind of colliders, and specific collision detection functions which I can dispatch dynamically that only use some of that data. (Practical example: a "Collider" would have a radius, and the coordinate for 2 points, and in case its type was "circle" it would only make use of the radius and of one of the 2 points - used as the center -, while if it was a "segment" it would only make use of the 2 points). My gut feeling is that this would bloat all colliders, and, even if the bloat could be reduced - using unions in some smart way for storing members? I wouldn't know how -, then still the design would be pretty brittle.
      I'm clueless and open for ideas and advice! How do you handle in general situations in which you have components that can be naturally modeled as subclasses of a more generic component class? Inheritance? Smart hacks with variants, templates, macros, custom indexing? Dynamic "internal" type?

Important Information

By using GameDev.net, you agree to our community Guidelines, Terms of Use, and Privacy Policy.

GameDev.net is your game development community. Create an account for your GameDev Portfolio and participate in the largest developer community in the games industry.

Sign me up!