How to Make Documentation Work for the People Using It

For a documentation owner or operational team, a document works when its readers can find the relevant truth, understand it and act correctly.

That sounds obvious. Yet documentation is often produced as evidence that somebody has documented the process rather than as a tool for the person making the next decision.

I learnt this on game projects ranging from a four-page description for a small title to a library of roughly 65 documents for a large console production. The examples are mine, not universal research findings. They are worth testing against the way readers use your own documentation.

A document is an operational interface

Writing is only the first part of documentation. The document sits between an author who holds context and a reader who needs to do something without that context.

If an operational reader cannot use it, the document has failed its frontline purpose - even when every required section exists. Audit, compliance and decision-history records may serve other audiences, but they should not be mistaken for operational guidance.

This is why centrally mandated templates often disappoint. They optimise consistency for the people governing the document set, while the people implementing the work need clarity about a specific decision, exception or dependency.

A template can help. It cannot substitute for understanding the reader.

Make the important path approachable

A large, intimidating document discourages use. Split long material into coherent sections. Use diagrams when they explain a relationship faster than prose. Provide a glossary when teams use the same word differently. Keep navigation predictable across related documents.

Consistency is useful when it removes search effort. A sound designer moved between projects should be able to locate sound requirements without learning a new document architecture each time. That does not mean a sports game and an action game need identical content. Standardise the route, not every answer.

Layer information around how it will be used:

• a short orientation explaining purpose, owner and current status;
• decision-ready summaries for people who genuinely need only the outcome;
• links to the authoritative detail;
• explicit signposts for teams likely to miss a dependency;
• a visible change history.

Do not make the summary a second source of truth.

Avoid duplicated facts

Prefer one authoritative source for an operational fact when uncontrolled copies could drift. Safety-critical or operational contexts may require deliberate repetition, but every maintained restatement needs the same owner and change discipline.

If the list of weapons appears in an introduction, a design section and an art plan, every change creates three opportunities for disagreement. Use one authoritative list and link to it from the other contexts.

Executive summaries are a common source of duplication because senior readers want the answer without opening a detailed section. Give them the decision, implication and link. Do not copy a changing data set merely to save one click.

The principle extends beyond documents. A process should have one authority for each rule, with other guidance explaining how to apply it rather than silently restating it.

State exclusions, not only inclusions

People will use documentation in ways the author did not expect.

I once used this deliberately ridiculous example: an artist sees five creatures listed in the sound-effects section and schedules five artists, one per creature. The game actually contains six creatures. The missing giraffe was omitted because giraffes have no sound effects.

The list was correct for the author’s purpose and dangerously incomplete for the reader’s purpose.

The fix is to list all six creatures and state: “Giraffe: no sound effects.” An explicit exclusion prevents a partial list from masquerading as a complete one.

This matters in architecture decisions, operational runbooks, policies and requirements. Name what is outside scope, what has no action and what must not be inferred from absence.

Remove ambiguity at the point of use

Consider this requirement:

All rhinos can be ridden by players of level 14 or above.

Does it mean every rhino is rideable and the player must be level 14? Or can lower-level players ride some rhinos while level-14 players can ride all of them?

Write the two facts separately:

Every rhino in the game can be ridden. Riding any rhino requires the player to be level 14 or above.

Clear writing is not cosmetic polish. Ambiguity becomes divergent implementation, inconsistent testing and arguments late in delivery.

The author does not need literary flair. They need enough command of the language and domain to recognise where a reasonable reader could make the wrong decision.

Design for scanning without encouraging blind spots

Readers under pressure will jump to the section they think applies to them. Telling them to read all 50 pages rarely changes that behaviour.

Make scanning safe. Cross-link dependencies. Put warnings beside the step where they matter. If the weapons team also needs the animal requirements because the rhinos carry particle cannons, say so in both navigational contexts while keeping the underlying fact in one authoritative place.

This is not duplicating the fact. It is duplicating the route to it.

Make change visible

A living document needs an owner, a current version and a reliable way to tell affected people what changed.

A concise change notice should state:

• what changed;
• who needs to care;
• whether the notice contains the whole change or links to essential detail;
• when the change becomes effective;
• who owns questions and corrections.

Version control helps, but storage history alone does not communicate operational impact. A technically perfect diff is not useful to a producer, designer or support team who does not know that their next action changed.

When the design is genuinely locked, change control can become stricter. Before then, documentation must keep pace with learning rather than preserve an obsolete decision because updating it is inconvenient.

Give reference material an owner

Large projects depend on facts the core team did not create: hardware requirements, regulations, technical specifications, product data or client policy.

If different people consult different internet sources, inconsistency enters the work invisibly. Assign ownership for important reference material. Store the accepted source where everybody can find it. Record provenance and date where currency matters. Correct one authority so the change can flow to every dependent decision.

This “project librarian” role may belong to a person, a team or a clear responsibility within another role. The name matters less than knowing who keeps shared facts trustworthy.

Test documentation against frontline work

Before mandating a document or template across an organisation, watch somebody use it on real work.

Can they find the answer? Do they understand the scope? Can they identify the current version? Does the prescribed structure expose the exception they face - or force them to create an unofficial note elsewhere?

There is no delivery process that works unchanged for every team. Documentation is part of that process. It should preserve necessary organisational knowledge without erasing the local context needed to apply it.

The best test is not whether the document passed review. It is whether the next person made a better decision because it existed.