Writing the right documentation
Final Fantasy V
During the past few months, I had a great time as part of the Game Production Community’s mentorship program. It was actually my first time as a mentor (and that might be a topic for a future blog post) but it was a great learning experience to have to organize my thoughts to be able to present them in a way that’s useful to someone else.
In particular, I was chatting with one of my mentees about a classic producer topic: documentation. I do think that documentation is generally a good thing for teams to do, and there are a lot of good reasons why you should create documentation. At the same time though, documentation should be written for a reason. The issue I saw my mentee running into (and that I’ve also seen when talking to other students or early career developers) is that since we preach that “documentation is good”, they write a lot of documentation because it’s what they feel like they “should do”. But, then they end up with documentation that they feel like no one else reads or documentation that is always out of date.
How do we ensure we’re writing the right documentation that people actually use?
Here are some questions I ask myself when deciding to write or asking others to write documentation that help me ensure we write documents that are actually useful to the team and that appropriate effort is spent writing them.
Who is this documentation for? What is its purpose?
Before even writing the first word of a new document, the most important thing you should do is get a clear idea of who the target audience for this documentation is and why writing it will be useful. You might be tempted to say “we’re documenting key information that anyone and everyone can read!”, but a specific and targeted document will always be more useful than something that is generic and has no clear target. Some examples of common target audiences and reasons to write documentation include:
Oneself
Game development is complex! There is a lot of stuff to remember from company-specific procedures to the roles of multiple team members, but there is no need to actually fit all that information inside your head. The documentation I make for myself tends to be looser and more disorganized as I can usually understand my own shorthand and quirks.
Members of the same team/discipline
There’s this admittedly morbid term you will see often in software engineering teams called the ”bus factor”: what is the risk we would lose key information if X team member was hit by a bus?
From a less morbid perspective, people leave teams/go on time off/(are laid off…) all the time, so we want to proactively share their knowledge with other members of the team to avoid issues when they are not available.
Usually, this type of documentation is domain-specific and will be shared with other members of the team (e.g. the specific settings needed to properly export a model’s animation will be shared with other members of the animation team) which gives you the liberty to keep things technical, as you can assume a base level of experience from the reader.
Members of other teams/disciplines
This category is one of the most important ones, as it is about ensuring clear collaboration between developers who might not be working as closely together or who have different skill sets.
Some examples are programmers preparing a guide on how the art team should import new 3D models to ensure they’re loaded into the game engine correctly, or the UI team preparing specifications so that the marketing team can create appropriate assets for in-game advertising. This type of documentation requires special care, as it’s easy to fall into the trap of writing something you think is easy to understand based on your experience but that might be undecipherable to team members from other teams/disciplines.
New members of the team
Another important category is onboarding documentation! Especially if you’re at a moment in time when you’re growing your team, having documents that ensure a new team member has as much information as they can about the organization helps make sure their onboarding goes smoothly.
How often will it be referenced? How important is the information it contains?
Once you’ve identified the target audience for a piece of documentation and why you’re writing it, it is good to know how often the document will be referenced. Naturally, it usually makes more sense to ensure you’re writing good documentation when it will be referenced often and/or be seen by many people.
Continuing with the onboarding documentation example, I’ve both been in situations where these documents were tremendously useful to align multiple new members, but I’ve also been in situations where it did not make sense to write an entire document when we were only planning to onboard a single new member and then had no intentions to add any more members to the team in the near future.
That said, identifying the importance of the information is key too — you might have documents that are not referenced often but that contain key information, such as the instructions for deploying a build or patch to a live environment. The cost of making mistakes here is high, so it is worth investing the time to document the information needed to ensure a smooth process even if you are not looking at the document often. As someone who helped co-found a company and handled the business side, one of the most useful documents I ever wrote was a guide on how to do the yearly business taxes, even if I only ever looked at it once a year!
Who will write this documentation? How often will it be maintained?
Writing documentation has a cost. There are times when as a producer you will be able to write the needed documentation, but there will also be many cases where you need to ask another team member to write the corresponding document. The time they spend writing documentation is time they could have spent on other development tasks, which makes it extremely important to justify the need for this documentation.
That said, even if you’re willing to pay this cost once, you also need to be clear on whether it’s a cost you’re willing to pay recurringly! Most documentation has to be maintained or else it will become out of date, which is especially a risk if it’s a document many people will reference for important tasks. Sometimes, the effort to keep a document up to date might make sense — for example, if you haven’t locked down the story yet and have a document outlining the key narrative beats, keeping this up-to-date with any important story changes will be important to ensure all downstream departments like writing or cutscene animation are able to appropriately plan the amount of work they will have to do later in development.
Eventually though, especially when you’re in mid to late development, it’ll make less sense to look at documents like these and more sense to actually look at task managers like Jira, the work being done and the game itself. And this is OK! Documentation also has a lifespan, so it’s useful to plan from the start how long you expect a certain document to be useful and need to be maintained, and when it’s OK to mark it as deprecated and clearly signal to the team that it is no longer a reliable source of information.
As you can see, there are multiple dimensions to think about when deciding to write documentation. It's a lot to think about, but if you make sure to spend time thinking about these factors before deciding to write a document just because "documentation is good", you're already going in the right direction!