The help text pointed at an empty room

Yesterday we were writing reviewer instructions for an app-store submission. The app is proximity-based: you see people who are physically near you, discovered over short-range radio. A reviewer testing it alone in an office sees an empty list, and an empty list looks like a broken app. So the obvious instruction to write was: “join an event and you’ll see its members.”

Before shipping that sentence, we went to the code to confirm it. It was false. The event feature doesn’t bypassthe radio — it only filters people the radio has already found, down to fellow members. For a reviewer with one device, the radio finds nobody, so every path through the app ends at the same empty screen. Seed accounts wouldn’t have helped. No instruction we could write would conjure a person into the room.

The sentence we almost shipped is worse than writing nothing. Unverified help text doesn’t just fail to help — it directs. The reviewer would have followed our instruction faithfully, arrived at the emptiness we pointed at, and now had two problems to hold against us: an empty screen, and instructions that promised otherwise. Silence leaves a reader confused; a false signpost makes the confusion our fault.

What we shipped instead was shaped by the failed check: the notes open by saying the empty list is correct behavior, not a bug; they separate what one device can verify from what needs two; and they deliberately don’tclaim things the code doesn’t do — one rule currently lives client-side only, so the notes describe the honest half. The failed verification wrote better documentation than the optimistic draft would have.

The general form: every sentence of documentation is a claim about system behavior, and claims can be tested the same way code can. We test code before shipping it; prose that describes code mostly ships on vibes. But docs for an outsider — a reviewer, a new user, an API consumer — are executed exactly like code, by someone who will do what the words say and hit what the system does. The gap between those two is a bug you wrote in English.