Introduction

On every team I've worked on over the years I've heard the same story.

I was trying to figure out this tool, but we have too much documentation on it

I was gunna try and find out how to do it, but we have way too much documentation

Yet I've also heard the exact opposite from people at the same time.

I was trying to figure out this tool, but we don't have any documentation on it

I was gunna try and find out how to do it, but I couldn't find any documentation for how

So how is it possible for both of these things to be true at the same time? How can we simultaneously have too muchdocumentation while also not having enough of it?

Well the reality is that they're not both true, but they stem from the same problem - it just feels like too much documentation.

I've worked on projects where a team has had years upon years of legacy documentation about what they're working on that simply hasn't been maintained, or where important information has been internalized by team members and simply not recorded. I've also worked on teams where they have had pages upon pages of empty documentation who also complained about having too much documentation despite this.

In both cases I'd argue the underlying issue is never that a team has too much documentation, it's that the documentation is, more often than not, simply unusable.

I'm personally a huge fan of documentation. Maybe it's the way I work or just my goldfish-like memory, but I love it. It's such a timesaver when you're stuck on solving a problem or needing more information from someone to simply pop open a Confluence page and find the answer right there waiting for you. It could be something you forgot, or something you never knew in the first place, but in every case almost always faster and easier than having to poke your coworkers to waste their time (and yours) teaching you how something works, rather than simply having that solution on hand in the first place.

When and where should I document?

Documentation is a lot like cleaning in a commercial kitchen - if you do it as you work or during lulls in activity, you'll be prepared for when you need it. Just like a kitchen will be all ready for the lunch rush if it's cleaned before it, you'll be ready to solve problems fast if your documentation is ready beforehand.

Generally I try to follow a rule of 3 when considering if something warrants documentation - if I encounter a problem that I need to investigate a solution for 3 times, it's a sign that I need to document something for future reference. The first investigation was probably me not knowing it in the first place, the second could have been me simply forgetting it, but the third time? It's a symptom that something needs recording for reference

This applies to other people too - if you've heard team members ask the same question or try to solve the same problem on 3 separate occasions, that's a sign it's not well documented and someone needs to correct it.

If a new team member has a question about something and you can't direct them to a document that answers it, that may also be a sign you need to record something!

Remember: good, usable documentation is not written just for you to reference, but the whole team.

In addition to this, every member of your team is responsible for keeping documentation updated and flagging when it needs updating. Always consult a page owner to make sure you're updating the document with the correct information; reference documentation is very frequently living and flexible and should always be changed whenever there's opportunity to bring it up to speed.

But how do you write usable documentation?

By keeping in mind a few simple concepts taught to me by a wonderful former professor of mine, Jeffrey Pidsadny.

Usable documentation is Searchable, Scannable and Readable.

Let's break this down:

Searchable

A usable document is Searchable by a user. They can navigate it with ease and understand where they need to go to find what they need.

This is a big one and where a lot of documentation tends to fall apart. You might have the best document in the world; you wrote your magnum opus, a completely impeccable treatise on how the entire game's gameplay should come together and play. But it doesn't matter how good that page is if nobody can find it to reference it.

"Searchable" is specifically for macro navigation: locating the page you need, finding the section that's relevant; basically enabling you to find the "right path" towards the information you need.

There's a lot of basic usability ideas that come into play here:

Build Your Own Discoverability Methods

In my experience, a big point of failure here is relying on something like the Confluence search bar to give users this power and assuming it will just work. Hey I get it - it's a search bar, it should enable you to search, right?

Confluence tends to filter things out or obfuscate pages that a user might be looking for. Especially in cases where a user might not know the exact term they need to be searching for (maybe it's a function in a tool they've never used before, or a concept mentioned in a page but not in the title) a Confluence search will make it hard for them. I've seen people give up on searching for a document entirely when said document definitely existed, all because they couldn't search for it in a search bar. This also puts a lot of expectation that someone writing documentation will be keeping that Confluence SEO in mind as they write it, which is rarely the case.

In the past I've combated this by compiling my own method for discoverability. There's many approaches that one can take; I've found compiling my own living document of resources to be incredibly effective for this, and allowing each team to manage their own empowers them to shape it to a way that works best for them.

For example, if a Level Designer can simply save a link to an "LD Resources" page and search for a relevant Level Design document in there, it's going to save them a boatload of time. That time otherwise would have been wasted sifting through pages from every other discipline on their road to finding a solution that they know is specific to the Level Design team. Searching one page for "Player Metrics" can often be easier and less time consuming than searching a bloated Confluence space for the same thing.

And if team members are encouraged to take ownership of their own compilations of resources they'll be able to shape it in a way that's the most effective for their purposes, ultimately freeing everyone from each saving quick links to the same two dozen pages on their web browsers bookmarks.

Titles: Short, accurate, specific

There's nothing worse than finding a page called "Asset Components" only to find that it's actually dedicated to just one specific component. Or finding a page called "How To Run The Build On A Mac And Not Have It Crash" - is this page about how to run the build on a Mac? Or just specifically about avoiding crashes, and the information on how to run it on a Mac is actually elsewhere?

When titling a page, don't just name it what you think the page is about - name it what any user should know the name is about. If the user doesn't know exactly what information they're going to find when they click the link to the page then the odds are good you're going to waste peoples time who are actually looking for different information altogether.

Trim The Fat

In some cases, your documentation may have lost its relevancy.

There's nothing worse than visiting a page that was "Last updated 8 years ago", or thinking you found a solution but it's actually just a blank page someone forgot about long ago.

On a case-by-case basis, look through them and see if they're still relevant. Maybe they're actually very accurate and just need an update or two. Keep in mind you don't need to delete pages entirely (maybe that 8 year old information will be useful? Maybe?) but at best, simply redirect users if the information is no longer relevant or a better resource exists.

Marking pages as "[ARCHIVED]" or moving them to an inaccessible location may help to keep them on hand but not bog down a user who may stumble across them on a search for other information, or a newer team member who might mistake them has being important when they're anything but.

Navigation!

Nav bars are your friend - so long as you're putting your pages in the right places, a nav bar lets users visualize your documentation structure and narrow their search to relevant sections. If you can have it as a persistent element on your database that a user can always look to for reference even better?

For example, if I can get to "player locomotion" by clicking down a hierarchy of "Project -> Game Design -> Player -> Player Movement", I'm definitely going to prefer doing that since I can easily build and understanding of the database's structure and page hierarchy, rather than the alternative of simply searching "Player Traversal Navigation Locomotion" etc, until I happen to get lucky with my wording!

And if you're worried about nav bars because all your documents won't fit very neatly in it - well then that might be a sign you have to Trim The Fat.

Scannable

Scannable encompasses the idea that once a user has successfully located the relevant document, they should be able to scan through it and find what they need quickly on a micro level (i.e. searching within a single page, section of document, etc.)

Documentation being scannable is important because it saves from users having to read the entire thing to get the information they need; if a user can glance at a section of document and know what it's talking about and if it's relevant to their needs then congratulations - it's scannable and therefore more usable!

Headers, Table of Contents, Page Numbers, oh my!

There's a reason that books have been using table of contents, page numbers and chapters for centuries - it's because they work!

I write a table of contents at the top of every page, with navigable links to headers on the page wherever possible. This means that a user who might be coming to my "AI" page to find out about pathfinding can simply click the header titled "Pathfinding" as soon as they open the page, instead of having to scroll down and read the whole document to find that information.

In a multiple-page document, page numbers and a table of contents allow the user to find the location of the information itself if it's indexed, or even communicate where exactly that information is.

Visual importance

Do you have something important to say that a user really needs to know in order to understand something? Or maybe a key point in a paragraph that will help the user understand the concept immensely? Bold it!

You might notice that if you read only the bolded text in the above paragraph you can actually get the whole idea without needing to read it! Tactics like this will help a user break down and digest bigger sections of text and analyses if they're relevant to their needs without having to read the whole thing.

Readable

Readable is one of the easier points to understand about documentation because it aligns with what most of us do when we write anyway. It ensures that a user reading your documentation can understand what it's saying, what you mean in the text, and it doesn't give them a headache trying to figure it out.

Know that you don't know your audience

As you're writing documentation, keep in mind who might reference it in the future. If you're working in a multidisciplinary studio odds are good that at some point in time your reader will not be someone you expect.

If you wrote a hard, technical write up about the physics implementation of the wheel traction in a racing game and you might expect only another gameplay programmer to read it. But what about the game designer who is designing the cars? A level designer investigating a bug where the track feels slippery? A tech artist modeling wheel degradation? Will these people understand these concepts or be hung out to dry?

The reality is, more people are going to see your documentation than you expect, often those in other disciplines entirely, so you should put in your best efforts to make it understandable by these people as well.

Image references

They say an image is worth a thousand words, and in most cases with documentation that's also true! One image can get across a point that might take a paragraph to explain.

You could say "Make sure you check the "Dev Launch" box is checked, the "Unlock controls" box is checked and uncheck the "Don't Initialize Audio On Start" box"...

...or you could simply add a screengrab picture showing the launch parameters you used.

Remember: it's easy to overlook a chunk of text, but an image will always stand out.

Proofread

Most people tend to do this anyway, but make sure your documentation is free of any significant spelling mistakes, grammar errors or anything else which might give a potential reader trouble with understanding you.

Hopefully some of these concepts helped to put you on a path towards cleaner, more usable and better documentation practices.

Ultimately I can't see a world where too much documentation exists; it's like complaining that a library has too many books in it - sure, not every dusty old tome would be directly relevant to your current needs, but those books are probably there for reference by someone else anyway.

At the end of the day, as long as you have a huge library and the means to find the book you're looking for then it's mission accomplished as far as I'm concerned.