Help Center Architecture

Payments knowledge base

Demonstration piece. Shipped client documentation is under NDA, so this was built to the same standard instead.

Same facts as the API error reference, written in the other register.

Problem: One painful problem, four different questions, and a help center that answered only the easiest of them.
Insight: Almost every reader arrives from a search result, part-way in, already annoyed. Writing the suite as though people start at the top serves a reader who does not exist.
Result: Four linked articles covering orientation, task, reference, and explanation, each written for a different moment in the same bad afternoon.

The full story

A declined payment generates four distinct questions, and they are not answered well by one article. What do I do now. What does this specific message mean. Why does this keep happening. Where do I even start. Collapsing them into a single page serves the first question adequately and the other three badly.

The suite separates them along the Diátaxis lines: a hub for orientation, a task article for the person who needs to act, a reference for the person who needs to decode a message, and an explanation for the person whose real problem is a habit, not a card. Each is complete on its own, because each is somebody's entry point, and each names the one thing to do next.

The hub was the hardest to get right. A help-center landing page written as an introduction assumes a reader who started at the top, and almost nobody did. So it opens with a triage table instead of a welcome: start with what you are seeing. The conceptual material that would normally open the page sits below the triage, where it helps the reader who wants it without delaying the one who does not.

Key decisions

Write the hub as a signpost rather than an introduction, because a reader who arrived from a search result and a reader who arrived from the navigation need opposite things, and the search reader is almost all of them.
Give the retry article a job: prevent a behavior. It leads with the consequence, that repeated attempts make the next one more likely to fail, because the mechanism is only persuasive after the reader knows why it matters to them.
State the same decline reasons here and in the developer error reference, and say so in both. One set of facts, two registers. The explicit cross-link is what stops the two from drifting into two different accounts of the same system.
Leave one reason out of the help center on purpose. A card reported lost or stolen has its own code in the developer reference, with an instruction to show it to the payer as a generic decline, because the person at the checkout may be the one who took the card.

What it taught me

The retry article was the hardest of the four, because it has to argue rather than instruct, and nobody arrives at a help page wanting to be told their instinct is wrong. I rewrote the opening three times. What finally worked was leading with the cost to them, before any explanation of how fraud systems read a run of declines.