How we keep our own documentation honest

A translation product sells one thing above all: that what it tells you is what the source said. It would be strange to hold the product to that standard and not the words around it. So when we rebuilt the guide this week — sixteen articles covering the language pack, the privacy model, every tool, the glossary, the subscription, and what to do when something goes wrong — we ran the drafts through the same kind of check we run on a translation: for every claim, find the thing that makes it true, or strike it.

What the first drafts got wrong

The drafts were written by people who know the product well, from memory, in one sitting. They read fluently. They were also wrong in eighteen places, and unverifiable in about twenty more. A few of them:

• "Press Esc to stop the current run." There is no such key; Stop is a button.
• "Drop several files and they queue." At the time, the page took one file and ignored the rest.
• "Every sentence you translate is remembered." The translation memory stores only sentences a person corrected — deliberately, so a machine draft can never be replayed as if it had been approved.
• "Dub produces a new video file." It produces the dubbed audio track and the subtitles; combining them into a video is not in the browser yet.
• "Move your subscription to another device from the account page." There is no seat transfer; a second device needs its own subscription, and the billing page says so plainly.

None of these were lies. Every one was the plausible product — the thing a reasonable person would assume, or the thing we had once planned. That is exactly what makes them dangerous in documentation: they survive proof-reading, because a proof-reader checks whether a sentence is well formed, not whether it is true.

The check

The check is mechanical and boring, which is why it works. Take each concrete claim in an article — a button label, a keyboard shortcut, a format, a size, a place where a file is stored, a thing the product promises to do — and find the code that makes it true. A label must match the shipped text exactly. A behaviour must trace to the function that does it. A number must come from a measurement. Anything that cannot be traced is marked unverified, and an unverified sentence does not ship.

Run over the drafts, the check returned a table of every claim with a verdict on each. The false ones were rewritten to say what the product does; the unverifiable ones were either verified the hard way or removed. When a new feature landed later the same day, the same check found four more wrong sentences in the one-page article written for it, before it went out.

Why this is part of the product

Three things follow from running the check, and we think each one is worth more than the polish it cost.

The documentation cannot drift. Numbers that can change — how many languages, the price, the pack size, the formats a tool accepts — are never typed into an article; they are read from the same tables the product reads. When the table changes, the page changes. The homepage once said "400+ languages" while the picker offered sixty-six. That class of error is now a failed build, not a discovery.

The privacy claim is written once. The sentence that carries the whole product — that with a pack installed, none of your text leaves your device — exists in one file, and a test fails if any page retypes a variant of it. A claim that lives in one place can be checked; a claim that lives in ten places is ten chances to soften it.

The changelog says what was broken. Every release gets an entry written for the person using the product, and fixes are listed as fixes. A changelog that only announces triumphs is marketing. One that says "this was broken, now it is not" is the reason anyone reads it twice.

The rule, in one sentence

No sentence about the product ships unless something in the product makes it true. It is the same rule we apply to a translated sentence, and it turns out to be just as hard to keep.

Is the guide generated automatically?

No. People write it. What is automatic is the check: numbers come from the product's own tables, the privacy claim is written once, and every concrete claim is traced to the code before it ships.

What happens when the product changes?

The article for that tool changes in the same release, and the changelog gets an entry. If a change makes a sentence untrue, the build fails or the check catches it — either way it does not stay up.

Where can I report a sentence that is wrong?

The support page. A wrong sentence in the guide is treated like a wrong translation: a defect, fixed in the next release, and named in the changelog.