Symptom-First Docs: Writing Game Troubleshooting Like an On-Call Runbook

Most troubleshooting pages are organized the way the author thinks: by feature. "Radar", "Eggs", "Pets", "Settings". The reader shows up with something different in their head: I pressed the button and nothing happened. They don't know which feature is broken. That's the whole reason they're on the page.

On-call runbooks solved this years ago. You don't open a runbook to the "Postgres" chapter; you open it to the alert that just fired, "replica lag > 30s", and the first line tells you what to check. I wanted to see how well that structure carries over to player-facing docs, so I studied a troubleshooting guide written for the Roblox game Ride A Pet. It turned out to be a clean example of the pattern.

1. The entry point is a symptom table

The page opens with a two-column table: Problem → Start here. The problems are written the way a player would say them:

Notice what's not in the left column: internal names. Nobody types "radar activation state" into a search box. They type "bought radar can't find egg".

The runbook equivalent is naming alerts after user-visible impact ("checkout errors > 2%") rather than after the component ("svc-payments-5xx").

2. One first check, before anything else

Each section starts with the single cheapest check. For the radar case it's literally: first check whether the radar is equipped. Buying it in the shop and activating it with "Use Radar" are two separate actions, and the most common failure is doing only the first one.

That's the runbook habit of checking the cheapest, most likely cause first. Note that it's written as an instruction, not as a made-up "this fixes it 80% of the time" claim. Nobody measured that, so the page doesn't say it.

Other first checks on the page follow the same shape:

• Egg won't enter the basket → check the Egg Basket first. If it's full, go home and process what you already carry.
• Home but no new pet → is the egg still in your basket? Then it never reached the nest; use "Place Egg In Nest" again.
• Wallet not growing→ is the pet actually placed on the plot? Then look at its $…/s field and any collect action beside it.

3. Tell people what not to do

Runbooks have "do not restart the primary" lines for a reason. Player docs need them too, and this page has a whole block of them:

• Changing several things at once. Try the fix for the current symptom, then see if that action works.
• Restarting immediately while carrying an egg. Finish delivery first if you can.
• Paying again because an interaction looks stuck. Check the result and account state before repeating a purchase.

The third one is the important one. In a game with a shop, "it didn't work, so I'll buy it again" is the user-facing version of retrying a non-idempotent request. Calling it out explicitly protects the reader's money.

4. Separate "slow" from "slow"

The best section on the page is about performance, because it splits two problems players routinely mix up:

• The pet is slow. That's a game value. The page says to compare the same movement field on both pets, on the same route, in the same carrying state (don't compare one pet riding empty with another carrying an egg).
• The client is slow. That's rendering or network. Lower Graphics Quality via Esc → Settings, close heavy apps, try a steadier connection. The page is explicit that these changes help rendering and leave the pet's in-game speed value unchanged.

If you've ever had a "the API is slow" ticket that turned out to be a slow laptop, you know why that sentence is worth writing down.

5. Escalation with a privacy note

Runbooks end with "if none of this worked, page X". The page does the same: Roblox Status for platform incidents, Roblox Support for account and billing, the developer's official links for game bugs. It also lists what to include in a report: device, OS, approximate time and timezone, the action attempted, the exact error, and a screenshot of the relevant basket, pet, nest or shop state.

And then one line that most support docs forget: keep passwords, account cookies and payment-card details out of screenshots and public reports. On a Roblox guide, that line may do more good than the rest of the section.

A worked example

If you want to see the whole structure in one place, read the Ride A Pet stuck egg and lag fixes page top to bottom with a runbook in mind: symptom table, one first check per section, a "common mistakes" block, then escalation.

A template you can steal

Here's the shape I'd reuse for any product's troubleshooting doc:

- symptom: "You bought a radar but cannot find a target"   # user's words
  first_check: "Is the radar equipped? Buying and using are separate."
  then:
    - "Sold out? Use the restock countdown, don't spam Buy."
    - "Target needs a requirement you lack? Pick another target."
    - "Marker on empty ground? Check elevation/cover, re-read the target list."
  do_not:
    - "Buy a different item before checking the first step"
  escalate_to: "Developer links on the official page"
  include_in_report: [device, os, time_and_timezone, action, exact_error, screenshot]

Four rules to go with it:

1. Name sections after symptoms, in the reader's words.
2. Lead with one cheap check, not a list of ten.
3. Write the "don't" lines, especially anything involving money or data loss.
4. Split look-alike problems (slow value vs slow client) explicitly.

None of this is specific to games. It's just what on-call engineers learned the hard way, applied to the people who aren't on call but are just as stuck.