2016-07-31

Logging and Documentation

01

It is really important to make documentation and to log what has been done. It requires very little effort and helps everyone out in the long run. In this post I will discuss the benefits of documentation and what to look for in creating good documentation. This may be a little wordy but is worth the effort to read and consider in future projects.

Benefits of documentation

Remembering how the game should be played or how the code is structured.

Forgetting is a bigger problem when you want to build upon previous work or if other people get involved where being organized will make for a smoother project experience. Documentation in the form of rule sheets, templates and gameplay videos allow others to know how the game should be.

Being able to recall how things went or recount how things were to someone else.

There may be a time when there is a need to talk about the project. Having documentation lessens the effort needed to present what has been done and any details that could be missed if it were done by memory. If you were getting paid for this project, for example, you would be able to justify the amount of hours it took to get to the results and give an outline of what went into the process/development.

Having evidence that team members have gone through the motions of a project which results cannot provide.

This kind of documentation is usually in the form of reflections where one can eventually write up a blog post or a shortform research paper.

It makes for good presentation material.

Having photos/videos of the process and happenings helps make the project much more interesting. Anyone interested in the project would not need to imagine how things were if they can see it from a photo or video.

Creating documentation

02

Using a readme

Usually it's natural for people to look for a readme file. It should at least contain all the information needed for someone to get the game running. You may then add credits, contact, licensing information and anything the player will need to know when setting up or playing.

Rules and rule sheets

If making a tabletop game then having a rule sheet is necessary for players to know how the game should be experienced. Here you could include the following:

Templates

If there is a need to construct anything the use of templates would help make that easier. Templates may also be forms which may help with scoring and it is helpful to have files which can be printed out when they run out.

Gameplay video

Something that shows the fun of the game or the general idea of how the game is can encourage others to know what the experience is like and if they would be interested in it. It is best to keep it between 20 seconds to a minute long. While the minimum time may seem arbitrary it is just long enough for someone to still choose not to commit to the game. Any shorter and there may not be enough information about the game. Any longer than a minute and you may be wasting time that could be spent downloading and playing the game.

Photography

Here is where a collection of photos would help future documentation. Images help liven written text greatly as good placement let's the eyes rest while giving some variation. Photos also help show readers how things were and allows documentation to describe the setting and details without having to resort to writing a lot of imagery.

Process/development video

While this is similar to having photography in that it gives variation to written documentation and helps describe setting and details, videos also serve to provide more of the experience of being there and being part of the process and development. In this way there may be other details that can be revealed which photos may be unable to convey as easily.

Written reflection/blog

During the happening of the event, these may take the form of bulleted notes or audio/video recordings and photos. Reflections also allow the author to relive some of the process with some of the thinking and state of mind at the time.

Evaluation

These may be in a myriad of formats, but should allow the author to relive some of the moments where decisions were being made and what led up to that point of the project. During the course of the event they help measure the progress and success of the decisions if a metric to measure such things have been established.