Poorly formatted documents are one of the primary reasons why people don't read them.

I bet you've seen something like this before:

• Long walls of text that take hours to scroll through
• Useless introductions that drive no information
• Massive amounts of data to scan all at once.

A complete mess that lasts a few months before everyone ignores it.

Writing good documentation is one of the most important skills for a Modern Game Designer. It makes you clarify your thinking, correctly organize game information and communicate at your best with others. This week we'll see the 5 common mistakes that Game Designers (even experts) make that result in a poorly formatted GDD (Game Design Documents).

Writing docs is your main activity as a Game Designer, so you better avoid these pitfalls fast.

‍

To format perfect documents, you want to avoid:

• Ignoring Who’s The Reader
• Lack Of Document Hierarchy
• Lack Of Structured Content
• Ignoring Usability And Readability
• Documents Inconsistency

Without further ado, let’s jump right in.

#1: Ignoring Who’s The Reader

Who you write for changes how you write.

If you write for a technical person or an artist, you cannot write the same type of document. Simply because they have different backgrounds and thus a "different working language".

By ignoring your target reader, you'll end up with misunderstanding, confusion, and overlooking important details. You'll end up with completely useless documents. And the damage is doubled since both of you have lost precious time and need to delay other work.

Fixing this is simple: consider who your reader is.

‍

Write with your #1 reader in mind: programmers.

Anyone needing information about the game's work can read Game Design Documents. But most of the time, programmers will read it during production to implement the features you designed.

This means you must keep them in mind every time you write documents. Consider their requirements, the language they use, and how they think while working. If you have no idea about these things, engage with them to get a glimpse of their world. You don't need to replace them; just understand how they think and work daily to address it in your documentation.

If you do this, programmers will appreciate it so much.

#2: Lack Of Document Hierarchy

Ignoring document hierarchy makes it daunting to search for information.

A document without a proper structure is 100% guaranteed to be ignored. Why? Because people want to focus on absorbing information rather than wasting mental effort in understanding how to read a messy document. With no structure, readers will have a hard time finding information and end up overwhelmed with content.

But most importantly, they will focus on things they don’t need due to a bad document flow. This increases frustration and makes them waste precious time.

To fix this, add structure while keeping a specific kind of mindset…

‍

Organize your document page for "skimmability".

To "skim a text" means flying over it with your eyes grasping what the doc is about but ditching the details. The bare minimum to achieve this is to split your document with headings and their relevant subheadings.

This newsletter piece is not an exception at all! I formatted the text with 1 subheading for each mistake so you always know where you are. As you can see, the document is much more readable with just this simple structure.

You basically have a compass to move back and forth in the text without losing crucial information.

#3 Lack Of Structured Content

There are many things plain text can’t efficiently explain.

Text is the best way to describe something without something better. And when you have some game design documents behind you, you realize that there are many situations where text is not the best choice.

Some examples plain text has a hard time explaining:

• Visual style and mood
• Gameplay mechanics
• Spatial relationships
• Animations
• Visual and auditory feedback

And more.

That said, don’t push too much against plain text; it’s a good solution in many situations.

You just need to be aware that it’s not the only solution.

‍

The more you leverage documentation software features, the better.

Depending on the platform you write documentation on, you can choose from more or less options. However, images and tables are always available (if they're not, change software).

Use them whenever you feel the need to increase readability exponentially. If you use more complex software (like Notion, among many), you can add databases, other software embeds, callouts, foldouts, dividers, etc. Without going overboard, the more structured content you can use, the better.

You can appreciate the difference between using structured content and not in the 2 images below.

‍

#4 Ignoring Usability And Readability

Usability and readability issues make your docs destroy your Production work.

Think of a Game Design Document as a User Interface for knowledge consumption. Just as a poorly designed UI hurts usability, a document with bad readability can hurt the reader's understanding.

Writing a document with illegible fonts, strained eye colors, bad layout, etc., will make Production work mentally heavy. These seem minor tweaks. But they're not because they make a huge difference when they add up, especially in the Production Phase, where efficiency is king.

To fix this, let's borrow some technical details from human reading psychology.

‍

Create a reading experience considering how human beings engage with a text.

Let’s face it. People don’t read; they scan (especially on the web).

They read deeply only when they have a solid grasp of what the document is about and the text is manageable. So usability and readability are among the top concerns if you want people to engage with your documents.

Always consider:

• Legible font style and size (use sans-serif fonts)
• White space (smash that Enter key from time to time!)
• Unnecessary words and sentences (concise + detailed = perfection)
• Bullet points (like these 😄)
• Bold, italics, and underlined

Be mindful of where and how you use these tools.

Remember that people judge on first impressions (whether or not they believe it), so address it to create a pleasurable reading experience.

#5 Documents Inconsistency

Inconsistency leads to misunderstanding, confusion, and useless mental effort.

If you have one or more sections of your GDD that have a different structure than others for no reason, you have inconsistent documentation. And that’s a problem.

It gets easily overlooked because you’re so focused on your work that you don’t notice it. But, unfortunately, this is an obvious thing to spot for people who read your docs. It’s a mental effort that has nothing to do with understanding the material but accessing it in the first place.

So do your best to keep the structure the same throughout the GDD to make the reading a pleasurable experience.

But how can you do it without going crazy?

‍

Create (and follow) templates and guidelines for the whole team.

Believing that anyone in the team (even your future self) could never forget the structure they need to maintain is nuts. Game Designers have a lot of work to manage, and they cannot waste time reinventing the wheel whenever they need to write a doc. That’s why a team (but even a solo) MUST have templates and guidelines. This ensures that you 100% follow the same structure and make writing and reading a breeze.

Every formatting decision always aims to reduce the mental effort required to work on documentation.

With all these tools available, bad documentation is just a (bad) choice.

Key Takeaways:

• Write documents with programmers in mind.
• Organize your document for skimmability.
• Leverage structured content as much as you need.
• Increase readability by considering how humans read text.
• Create and follow templates and guidelines to not reinvent the wheel.

‍

I’ve also talked about Game Design Documents in previous Game Design Compass episodes:

• 👉 What Documents Should A Game Designer Focus On?
• 👉 4 Reasons Why You MUST Write Game Design Documents
• 👉 Wiki Format In Game Design Docs: 4 Key Reasons It Outshines The Single Giant Document
• 👉 How To Build A GDD Wiki Home Page That Boosts Efficiency And Collaboration
• 👉 Game Design Documents: 3 Effective Tips To Use Them And Boost Your Design Process

Check them out if you want to dive deeper.