必須先判斷故障所在的維修指南

A repair manual that has to know what is broken

Most "how to fix X" content is a list of steps. It assumes you already know what the fault is. That assumption is where most home repairs actually fail: someone watches a video about replacing a fill valve when the real problem is the flapper, and buys the wrong part.

So the design question I started from was not "how do I write instructions" but "how do I get from symptom to part without a technician". That changes the shape of everything.

The unit is a machine, not an article

Each guide opens with an animated diagram of the thing the user already owns — a tap, a toilet, a drain. The parts move because the mechanism is the explanation. A static drawing of a toilet tells you nothing about why it keeps running; a diagram where the flapper lifts and the fill valve opens shows you the failure before you read a word.

The diagram is not a video. Video is heavy, unsearchable, and impossible to pause on the exact frame that matters; it also cannot be re-rendered when the interface language changes. In the walkthrough the parts move as you go, so the explanation and the step are the same object rather than a picture sitting beside a paragraph.

Diagnosis is a tree, not a form

The diagnosis is two or three questions, and the answers are not a form submission — they are local state that narrows a decision tree. The tree is data rather than code, roughly:

{
  "id": "toilet-running",
  "question": "Does the water stop if you lift the float?",
  "yes": { "goto": "fill-valve" },
  "no":  { "goto": "flapper-seat" }
}

Two properties matter here. First, the tree has to be finite and small — if a symptom needs five questions, it is usually two different faults wearing one description, and the guide should be split. Second, every leaf must point at a part the user can actually see and name, or the diagnosis is useless in practice.

Everything runs client-side. There is no server deciding what to show, which means the whole thing works offline once loaded, and there is no analytics pipeline recording what broke in someone's bathroom.

The practice round is the part people skip

Before the walkthrough, there is a practice round: pick the right action without hints, wrong picks cost a mark. This came from watching how people actually use repair guides — they read the steps, nod, then open the thing and immediately lose track of which screw they were on.

The practice round is cheap to build (it is the same step data with the hints removed and a scoring wrapper) and it changes behaviour more than any amount of explanatory text. It is also the only part of the site that resembles a game, and I resisted making it more game-like on purpose: a repair guide that feels like a mobile game gets dismissed by the person who is standing in front of a leaking toilet at 11pm.

Four languages, not one language machine-translated

The site ships in English, Chinese, French and Spanish. The guides are written per language rather than translated by pipeline — the parts have different names in different markets, and a literal translation of "flapper" produces something no French hardware shop will recognise.

That is expensive, and it is the main reason the coverage is a set of common faults rather than an encyclopedia. The alternative — machine translation of 400 guides — would produce a site that ranks in four languages and helps in none.

What is not there

No account, no saved history, no "your garage" dashboard. The guides run in the browser and store nothing. That is a real limitation for anyone maintaining several properties, and it is the price of not having a login wall in front of a dripping tap.

The site is new, and it covers a small set of faults. It is not a substitute for a professional on gas, mains electrical, or anything structural — the site says so rather than hiding it in a footer.

If you want to see how the diagnosis and the animation behave together, the tap guide is the shortest path through all of it: supperman.net/faucet.