Workflow

A document QA workflow is nine passes, in one order.

Documents fail slowly. A missing heading breaks navigation, an unsourced figure survives three reviews, a superseded version keeps circulating. Each has a cheap pass that catches it, and the order is what keeps the pass cheap.

Why documents fail in ways code does not

Code fails loudly when it fails at all. A document fails quietly: it renders, it reads fluently, and the number in paragraph four is wrong for six months. Nothing errors, so nothing is investigated.

The second difference is reader behaviour. Nobody reads a document end to end, including the people who approved it. They scan headings, jump to the section they need and trust the rest, which is why structural failure is a content failure rather than a formatting one.

That combination is what a workflow has to beat. Each pass below targets a defect class a reader would miss and a machine can narrow.

Pass one: classify the document before anything else

Classification decides the standard, so it comes first. A public marketing page, an internal process note, a client deliverable and a regulated statement do not share thresholds for claims or tolerance for hedging.

It also decides where the check can run. Anything confidential is checked locally, in the browser, so no copy leaves the machine; anything public can go through whatever pipeline you prefer.

Write the class on the document, not in someone's memory. The classification is what makes the later passes consistent instead of personal.

Pass two: the structural pass

Read the headings alone, in order. There should be one level-one heading, no skipped ranks, and no duplicate section titles. That is what exports, tables of contents and inbound anchor links depend on.

Then read what each heading promises and check the section delivers it. A heading that could sit on any document in its category is a heading that does no work, and the paragraph under it is usually a restatement.

Finally look at block length. Blocks past 220 words read as a wall on a phone, and splitting at the point where the subject changes costs nothing.

Pass three: the claim pass

List every assertion: numbers, dates, quotes, comparisons, superlatives, promises about outcomes. For each, either attach a source a reader can open, or narrow the sentence to what you can support.

Do the sourcing before the rewriting, always. Rewriting an unsupported statistic into vagueness removes the finding and keeps the misinformation, which is strictly worse because it becomes harder to challenge.

Generated drafts concentrate claims where they sound most authoritative: the opening statistic, the proof block, the comparison table. Read those paragraphs twice and the descriptive ones once.

Pass four: tables and data

A table is a claim about structure. Every row should have the same number of cells, every column a name, and every unit stated once in the header rather than repeated inconsistently in the cells.

Check the join column first if the table feeds anything. Identifiers lose leading zeros in a spreadsheet, dates arrive in three formats, and a currency symbol appears in half the cells. All of that survives review and breaks an import.

Sample ten rows and read them. That is where invented values, impossible dates and duplicate records become obvious to a person and invisible to a parser.

Pass six: accessibility

Descriptive alt text on every informative image, an empty alt attribute on decorative ones, and never a filename repeated as a description. One sentence each, describing what the image contributes.

Headings matter here too, because assistive technology navigates by them. A document with visual-only headings is a document with no structure at all to a screen reader.

Then link text: sign-up form rather than click here. A reader navigating by links hears only the link text, and a page of here tells them nothing.

Pass seven: readability and voice

Measure sentence length spread rather than average, since uniform sentences tire a reader regardless of how short they are. Cut one sentence per section hard and let another carry the detail.

Then check the tells: stock transitions, inflated verbs, hedging that asserts nothing, absolutes with no evidence, the same phrase returning with a synonym swapped.

Edit for the reader, not the rule. Removing a flagged phrase without replacing its function leaves a sentence with a hole where a verb used to be.

Pass eight: versioning and the change log

Name the version and the date on the document itself, not only in a filename nobody sees. A reader who has printed a page needs to know whether it is current.

Keep a short change log for anything operational: what changed, why, who asked. Three lines are enough, and they answer the question that otherwise becomes a meeting.

Mark superseded documents as superseded. Two live versions of a process is a failure mode that costs more than any typo, and it is the one nobody puts in a QA plan.

Pass nine: sign-off and the record

For anything with consequence, a named reader signs a stated scope: reviewed the eligibility wording and the pricing table, for example. Approved on its own says nothing you can rely on later.

Keep the record small and portable: the check report, the decision, the reviewer, the date and the version. Store it with the document rather than only inside a tool that outlives the project differently.

Then sample published documents quarterly. Template changes and expiry dates are what reintroduce defects after a clean launch, and both are invisible without a look.

What this covers

  • Classification

    Public, internal, client or regulated, recorded on the document itself.

  • Structure

    One level-one heading, no skipped ranks, no duplicate sections, blocks under 220 words.

  • Claims

    Openable source per figure, or the claim narrowed rather than blurred.

  • Tables

    Equal cells per row, named columns, one unit per column, join column intact.

  • Sign-off

    Named reviewer, stated scope, version and date kept with the document.

Questions this page usually raises

How long should a document QA pass take?
The structural pass takes minutes with a checker. The claim pass takes as long as the document has numbers in it, and that is the pass worth protecting.
Can the whole workflow run on a generated document?
Yes. Generated documents need passes three and eight more than most, because claims arrive unsourced and versioning is usually absent.
Do we need a checklist for every document?
No. Apply the full sequence to anything client-facing, regulated or operational. A memo for four colleagues needs the structural pass and nothing else.
Where does human review fit?
At the end, scoped to what a machine cannot judge: whether the argument holds and whether the claim is defensible. It starts from the automated report rather than repeating it.
Does the check require uploading the document?
No. Markdown, HTML, CSV and JSON are parsed in the browser, which is what makes the workflow usable on client and pre-release material.

Document QA workflow

Run the checks, then decide who has to sign it.

The automated pass is free, needs no account and uploads nothing. Escalate to a named reviewer only where being wrong is expensive.