Category: Best practice

Game-as-a-service game design is ongoing and iterative by nature: the launch version usually only contains a core set of features. Based on your predictions and the feedback you receive from players you want to add or extend features later on. This leads to many small game design documents. A certain fractality is added by the fact that single features can also come with their own release roadmaps. This approach calls for a certain way of documentation that boils down into three steps:

Documenting the future

At this stage the feature or the whole game exists only in your head. You use written vision summaries, player stories, mockups/wireframes, flow charts and if required Machinations diagrams to communicate what the feature is all about. Documenting the future gets the development process going, which brings the feature into the present.

Instead of creating a Google document or a Wiki page for the initial documentation, start with creating a new issue in the issue tracking tool of your choice. I usually work with Jira/Greenhopper and hence will use it as an example. The issue can contain the initial feature description as detailed as necessary. Embed screenshots or link to external documents if required. The advantage is that the initial documentation does not live in a remote place somewhere in your knowledge base but right in the centre of your development and planning process – the agile planning board. Simply put the issue on the backlog, assign it to the team member you need feedback from and add others as watchers if necessary.

Initial feedback, questions and answers can be added in form of comments to get things going and to pull the feature from the future into the present. Other team members can create sub-tasks and request additional documentation. The fractality comes into play where you use Jira to create a roadmap for the feature itself and not only for the game as a whole. The issue works likes a documentation hub: step by step the issue can link to additional external documents like Google documents or spreadsheets where more detailed information can be found.

Documenting the present

When the feature enters the present it means development has started. This is also the point in time when your theories might fall apart because no plan survives contact with reality. Again it makes a lot of sense to add your findings and decisions in form of comments to the issue. Six weeks down the road someone might ask you why you went for solution A and not solution B or C. Answering that question might actually be quite difficult. Using the issue as a documentation hub can help by reading through the comments to understand the flow of thoughts at that stage.

Here are some reasons why documenting using a issue tracking tool helps the team to stay on the same level of knowledge:

• The feature is accessible straight from the agile planning board, including its documentation and external links. That helps to keep things in focus.
• You can add sub-tasks to the issue or turn it into an Epic. Again, the essential information follows the issue through the development process. There is no separation between information and process. In my experience some developers simply forget where to look for the information they need. They forget that you put that document on Google Drive a couple of weeks ago. What they do not forget is the issue they are currently working on!
• You can change the priority of the issue, add or remove watchers, assign it to other team members, resolve, reopen, and do other useful things with it. An issue works much better as an information radiator because it is more “in everyone’s face” than a Google doc or Wiki page somewhere else. This is especially helpful when you work in a distributed/remote team setup.
• Issues are also a good place to iterate over graphics and UI designs. It might take a bit of persuasion at the beginning to convince graphic artists that using an issue tracking system is helpful. The advantages become obvious quite quickly: No more searching for e-mails with feedback and screenshots. Instead everyone can follow the whole evolution of an asset via the comment stream of an issue.

Documenting the past

Congratulations! The feature has been released. Now it is time to wrap it up and finally put the documentation in a central Google Doc or on a Wiki page. Now the game design documentation turns from being a process assistant into a lore keeper. A game-as-a-service might be live for many years, so if the job of nurturing the experience moves to someone else further down the road, having a documentation of the past helps a lot. Setting up a documentation structure that makes information accessible instead of hiding it is a challenge in itself, though. While issues are volatile (they want to be closed eventually) the documentation on Google Drive or another online knowledge base is there to stay.