Dev Blog Week 3.5

Game

Spook House

8 years ago

Dev Blog Week 3.5

On Design
Design documentation is a strange beast; like many facets of design, there is no single approach that perfectly suits all projects. Even when aspects such as team size, composition, available money and time, technological access, or other contributing factors remain constant, the project itself will naturally tend towards needing more of certain types of information. In the case of a current project I am consulting on, Spookhouse, that information is system diagrams (more on that soon). As such, designers must not only evaluate what information to document and share, but also consider which methods of sharing are most effective.

All documentation at its core is about communication and reification (i.e. to concretely express an abstract idea). As such, design documents always seems to hit the same barriers:

· Scope: there is too much information or not enough

· Organization: the complexity of the material makes it difficult to present clearly

· Understanding: the document is tedious to comprehend for anyone other than the author

· Permanence: by the time the idea is documented, it is already outdated and must be revised (my least favorite).

These issues are common and certainly did not escape the early documentation of Spookhouse. For example, here is the preliminary draft of Spookhouse’s main system diagram:

(Attachment Below)

image
Whew that’s a lot of arrows, and a clear demonstration of the third issue mentioned, understanding – to anyone other than the author detangling and parsing the information here is quite the mental task. In our conversations on how best to move forward with the system diagram, it was clear the next step was to translate it into digital format: helping both the diagram’s legibility as well as its organization.

However, that still left us with the question of scope and permanence: is what is presented here too complex? Does it need to be broken down? Secondly, how will the diagram change overtime – what is the best way to communicate these changes?

Both system designer Blake Rebeck and I saw this diagram as the crux to understanding the underlying systems within Spookhouse. We wanted something that properly covered the complexity of the game’s interactions, while still being flexible (to update) and easy enough to navigate. Furthermore, this main diagram only shows a high level representation of how the features in Spookhouse interact, leaving most of the nuts and bolts to be delineated in other documents. As such it was important to us that the system’s diagram and documentation speak to each other directly. With this in mind we looked into various digital tools that would provide the best blend of representing the game’s systemic relationships while still being easy to navigate and update on the fly. Here is our solution, created and refined by Blake using the free online application draw.io:

(Attachment Below)

While the above diagram is certainly more visually pleasing and understandable, the true benefit lies in the fact that draw.io is not just a tool for creating diagrams, but also seamlessly integrates with Google Drive as well as Atlassian products such as JIRA or Confluence. This means that each node on the above diagram links to an external document that details a sub-system or feature of the game. This allows for an abstracted overview of the game’s systemic interactions, without having to navigate back and forth between a static diagram and a design document overview page – the diagram IS the overview page. Let us look at how the integration of draw.io helps to alleviate the aforementioned issues of organization, understanding, scope, and permanence.

Organization/Understanding
Like many diagram software packages, draw.io comes with a range of organizational tools such as grid-based alignments, pre-made charts or connection trees, or various features to organize by size, color, shape, etc. In addition to this, and less commonly included, draw.io provides collaborative features that integrate directly with Google Drive and JIRA. Here is an example:

(Attachment Below)

image

The above image illustrates the author’s ability to easily link to external documents, as well as provide small snippets of meta-data to help other team-members understand the contents and purpose of the node. Likewise, draw.io allows components to be sorted or hidden based of this meta-data. For example, if three nodes are declared as “Core-Loop”, sorting by the term will temporarily hide any nodes not declared Core-Loop (similar sorting methods are provided for color and shape). This is a useful tool for allowing the diagram to keep its richness in complexity, while giving viewers a method to sort extraneous information for the time-being – assuming a proper filter legend is provided.

Permanence
The use of meta-data within Draw.io provides additional benefits for updating information quickly and easily. For example:

(Attachment Below)

image
By declaring a textbox as “I’m with %group%”, dragging to or changing the text-box’s container means the text is updated based on the meta-data within the container. This can be useful for updating large sections of a diagram by changing the group’s meta-data.

One of the greatest benefits though, of having the diagram live in a collaborative program is that it can be a living-document. This phrase is often used to describe documents that are frequently updated and changed – comments or queries are left, resolved, and incorporated into the diagram/document as the project grows and changes. This practice is well supported by draw.io, which includes an extensive time-stamped revision history, allowing members to see the diagram’s progression over time and promote revisions and refinements (without fear of losing previous versions).

Scope
Finally, while the use of sorting via meta-data helps alleviate some of the concerns of an overly complex diagram, having the live diagram act as a hub for external documents further helps manage the concerns of scope. In essence, the question of whether an aspect of the system needs to be presented in the diagram is a matter of whether an external document is required. If there is no external document, what purpose does the element within the diagram serve and how might it be combined with other elements? This question has helped refine our scope of the diagram above and can even give insight into the nature of the component in question. A component without a supporting document may need to be rethought, which in turn can help change and improve the structure of the diagram.

Conclusion
While the above diagram and documentation method is by no-means perfect, it has shown itself to be a useful step in the right direction. As the game continues to grow, the methods for communication will as well – it is our hope that the aforementioned benefits of draw.io and integrating system diagrams with external documentation will prove a strong foundation for the changes that are yet to come.

If you’re interested in hearing more about our process, the benefits of diagram integration, or have your own suggestions – be sure to tweet us @SpookhouseGame or send us an email: hiddenpizzadev [at] gmail [dot] com.

Until the next post, stay spooky.