Introduction

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 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.

Basic Rules

I summarize the basics of my mindset in 3 Golden Rules:

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:

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).

Right way

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:

*example of headings being used to create a hierarchy - more on this on my Google Docs article

Right time

Now, remember Rule 3 and what it teaches you: documents are an investment. This means:

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.