Who doesn’t love some Documentation? Automatized Excel tables, Gantt Charts and 40 pages-long Design Documents analyzing your whole game. Amazing right?
I’ve been studying Game and Level Design for the last 3 years at AIV (Italian Videogame Academy) and obviously a big chunk of the school program has been about Documentation - during this time I had the chance to learn theory behind writing a Document, practice it and face all the problems that come with it.
Last year my Game Design teacher asked me to hold a Workshop about Technical Documentation, and while writing my script I started to notice how everything that I wanted to tell the students could be summarized in some Golden Rules; not only that, but I started to realize that good documentation writing is not about practical skills - it’s about having the right mindset.
This is going to be a 3 parts-long article serie, in which I’m going to cover these topics:
- The Golden Rules and the Mindset that they create, alongside general documentation good-practices and “when tos”;
- Theoretical and practical tips about Google Docs, while also sharing some tips and tricks;
- Theoretical and practical tips about Google Sheets, with more attention on how to make it less intimidating.
The reason why I prefer Google Docs and Sheets over Microsoft Office Word and Excel, is that not only are Google services free, but they are also integrated with Google Drive and have basically all the functions their Office counterparts have. Using Google services is basically a win-win scenario.
I summarize the basics of my mindset in 3 Golden Rules:
- Show, don’t Write: use images, videos and gifs whenever possible;
- Brief and short: use bullet points or tables, avoid walls of text;
- And the most important rule: documentation is useless.
Alright, one of those is not like the others. For those of you that picked up torches, pitchforks and pie charts to insurrect, let me explain these rules step by step:
Rule 1: Show, don’t Write
Trying to explain something to someone is hard. It’s even harder if you are trying to write it. Even if you are meticulous in describing every aspect of what you have in mind, when those information are processed by another person they won’t share your exact vision - it’s simply impossible.
This Rule needs to come to your mind whenever you are describing something in your Document: instead of thinking about how you can explain it, how can you visualize it?
Not only is this going to speed up your writing process, but it takes away all the interpreting part from your reader, making the Document clearer, faster to read and assuring you that anyone will understand what you mean.
Rule 2: Brief and short
You can ALWAYS write less. I like to quote Italian poet and writer Giuseppe Ungaretti when talking about this: in his poem Soldati (Soldiers) he describes in less than 10 words the full range of emotions that is felt by soldiers fighting in trenches.
If he could explain such complex human emotions in 10 words, we can do something similar.
Follow these steps to always write less:
- Short sentences, few words and lots of full stops:
- Cut the “and”, “or” and “so”,
- You don’t need synonyms,
- If you want to write “the weapon is cool and aggressive looking” write the most specific one (aggressive looking)
- Use the correct Dictionary and use abbreviations:
- For example: let's talk about Hollow Knight’s Checkpoint system (Benches):
- Instead of writing “The checkpoint object that allows the Player to change charms, regain health and save their position” I can just write “The Bench”;
- Remember to explain what “The Bench” means either in a previous paragraph or in an appropriate Document.
- Instead of writing “Main Character” all the time, I can write “The Main Character (MC)” the first time and, from there, keep on using “MC” on the whole Document.
- For example: let's talk about Hollow Knight’s Checkpoint system (Benches):
- Think of your Document’s Target:
- If you are writing for a Publisher, you might want to explain what you mean with words like “Agency” or use multiple words like “Player Freedom”;
- If you are writing for another Designer, it’s safe to assume that they know what Agency is, don’t lose precious word count on explaining it.
Rule 3: Documentation is useless
Let’s analyze this logically: what’s your goal as a developer? To make Games.
So, let’s say that your completed and published Game is worth 100 points, when you just start you are at 0 points. Let’s consider anything that brings your Game closer to the "completed and published” state (100) as a +1 - this can be anything, from a 3D model, to your main character movement script, to your first level.
Documentation is not one of these. Documentation is a +0. Hence, useless.
When you write a Document you are not advancing your Game forward - unless you are making a Game on Excel (which would be worthy of all the respect in the world). What you are doing is investing your time in an action that doesn’t bring your work forward hoping that the investment will pay off by allowing you to work faster at a later point.
This is essential since it forces you to evaluate thoroughly if the document (investment) you have in mind is going to be worth.
And this brings us to the fourth and secret rule.
Rule 4: No one is ever going to read 100% of your Document. Ever.
This Rule forces you to think about how you can minimize the amount of data that is lost in distraction or in the reader overlooking details thought to be unimportant. This Rule sums up your goal as a document writer: make sure that what’s important inside your document reaches the intended reader. The previous Rules all share this common goal, but they’re not enough. You need two more concepts: presentation (or the right way of writing a document) and timing (or the right time to write a document).
Remember Rule 1 and 2: a simple way to put it is “your document has to be nice to look at”.
Avoiding wall of texts and adding images will make your document more “nice”, but you have to pay attention to more than just that:
- Format your document to create a hierarchy and visually divide your content,
- Avoid breaking your topics between multiple pages whenever possible
- Format the text differently, cut sentences, reduce image sizes are some of your options
- NEVER break sentences between multiple pages
*example of headings being used to create a hierarchy - more on this on my Google Docs article
Now, remember Rule 3 and what it teaches you: documents are an investment. This means:
- Write most of your documents in pre-production:
- During this phase your team has to evaluate various possibilities, prototype a lot and throw away even more; it’s a production phase that is all about finding a way to go from 0 to 1;
- It’s the perfect time to work on a lot of +0s.
- Write your documents when you need them:
- Writing most of your documents doesn’t mean all of them,
- It’s useless to write a document about the progression system of your RPG-like character stats if you don’t even know if the final product is going to have RPG-like character stats.
- To sum this up: don’t overthink it.
Conclusions: what comes next
This introduction was meant to give you a rough understanding of my mindset. Hopefully now you share my vision on documentation and how to write it, but it would be even better if you don’t share it: use my mindset to create one of your own, destroy some of my principles, create more and then fine-tune everything to work with you, your workflow and your team.
Next step: I’m going to write two more articles, as mentioned before; one about Google Docs and one about Google Sheets. They’ll expand on this mindset and these four Rules, but they are going to be more on the technical side of things, exploring features, tools and tips and tricks, to show how to put these theories into practice.
Thank you for your time.