It's pretty clear and is common knowledge that no one reads design documents and you shouldn't expect people to. If you want people to understand something or give feedback on something, it's better to start with a powerpoint with lots of pretty pictures, a video, or a prototype.

But what the documents are actually for is a kind of sacred knowledge. Not on this Twitter.

When someone comes to you 6 months later and asks you a specific question about that feature that you have long-forgotten and haven't thought about in a while, what are you going to do?

It is essential to document everything in as much detail as you can so that you don't keep designing the same features over and over again without a good reason (this is not a good use of your time). Instead, you can just copy-paste a few paragraphs from Confluence to Jira.

Design documents are also a great way of communication between designers working on different parts of the game. And the bigger your design team is, the more critical they become. Designers (unlike everyone else) are expected to be able to read the rules.

But even other game designers will never read your document wholesale (as they shouldn't). Instead, they will use it to cross-reference their design with yours and see if there are any contradictions and inconsistencies. Much like lawyers read the law books.

To this end, the format used across the whole design team must always be the same. This way, you immediately know which part of the document to look at when you open it and don't waste time parsing unnecessary information.

Design your document for the user of the document. You know that people will be looking for a specific statement or a couple of statements. Make the job easy for them by formatting your text as a list. No one wants to read paragraphs about design – not even in D&D rulebooks.

Illustrating design documents is a huge timesink – not only the first time but also every time the design changes. It's 100 times faster to update text than images or videos, which is why images and videos often end up being outdated and often retire the whole document.

However, illustrations are also handy tools for explaining things, and you can't get rid of them – so what do? Sadly there isn't a magic trick, but I have a few tips (read on)

1. Illustrate only key things that really need illustrations. Very often younger designers will fall into the trap of illustrating every bullet and every sub-section of everything. This is not only unnecessary and wastes your time, but it also makes your design hard to read.

More to this point: think about the intended user of your design document the way you think about the player when designing the video game. What will they have a hard time visualizing? Illustrate that.

2. This one is a bit trivial, but I've seen people make bad choices here: use the software package that a) you know well and b) lets you modify the source file and doesn't flatten everything into a rasterized image. You will iterate on the illustration as much as on the document.

The importance of linking documents together can also not be understated. But why? Open any Wikipedia page and think about it: what do all the in-text links accomplish? That's right – discoverability! Someone who is a tourist in your design won't know what other documents exist.

...and a link will point them to the part of the wiki where they can read more about that other subject they were wondering about.

For coders among you: not having links in a design document is the equivalent of Ctrl+Click not working in Visual Studio.

Other ways to improve discoverability in a design wiki section:

- A landing page that tells the user who the owners of each section of design are, where to find what and where other related resources live

- A clear index of EVERYTHING. If a document is not in your table of contents, it does not exist.

- WIP and Obsolete markers. Often designs are in progress, outdated or being updated, but someone can go and read them! That's fine, as long as they know that it's not current.

For the love of God, make sure that all the terminology across your documents is consistent. If you name a feature "smack" in one place, then call it "smash" in another place and "bonk" in a third place, you've just generated a bunch of extra questions coming your way on Slack.

Two more points about naming conventions: I like to capitalize player-facing features, such as names of abilities (e.g. Launch) and enemies (e.g. Hiss Trooper). This differentiates them from under-the-hood things and helps readability as well. And keep it consistent too! (contd.)

DON'T RENAME THINGS!

Writers will come in halfway through your production and start renaming things. Hiss Troopers used to be called Knights in Control. By then, everyone on the team already knows the feature by its design name, and coders have named components and classes.

In design documents and internal communication, it's absolutely impossible to effectively rename an already-designed an implemented feature. By the time things get a narrative pass, it is way, way too late to change how it's called internally. And the code will never change.

If you must rename an implemented feature internally, just know that these will be the side effects:

- Half of the team will keep calling it by the old name
- Coders will all keep calling it by the old name because code won't rename it
- You will get more Slack messages

And finally (and this is important), make sure you "playtest" your document with other designers.

Maybe the detailed document reveals a discrepancy in what you agreed to.
Maybe your formatting is confusing.
Maybe you forgot something.
Maybe you should change a turn of phrase.

If you take one thing away from this thread, let it be this:




Design documents also need to be designed.




Thank you for coming to my TED talk.