One File Replaced Sixteen Help Pages: A Developer's Onboarding Cleanup

The screenshot was wrong again. A registrar had shipped a redesign over the weekend, the "Add a CNAME" button had moved, and by Monday our help page pointed customers at a screen that no longer existed. A ticket was already open. Someone on the team would spend the afternoon signing up for that registrar, walking the flow, capturing fresh images, and pushing an update. Two weeks later a different registrar would do the same thing.

That was the maintenance profile of our custom domain onboarding for a long time. We had one help article per registrar, and the count kept climbing. By the end there were sixteen of them. Each was a static page of numbered screenshots, and each was a small liability waiting for the vendor to change a color or rename a menu.

The patch cycle nobody signed up for

The loop was predictable enough that we could have printed it on a poster. A registrar changes its UI. Our screenshots rot. Customers follow instructions that no longer match what they see, and they fail. A bug gets filed. Someone updates the screenshots. Then it starts over somewhere else.

None of this was interesting engineering work. It was transcription. We were maintaining a museum of other companies' control panels, and the museum was always slightly out of date.

The deeper cost was not even the docs. It was the verification loop hiding behind them. After a customer told us they had added their records, we polled to check. When a value was wrong, we surfaced an error and sent them back to their registrar to fix it. Often they made it worse. They would edit the wrong record, add a duplicate, or paste a token with a trailing space. Now we were debugging a stranger's DNS zone through a support thread, one guess at a time.

We were maintaining a museum of other companies' control panels, and the museum was always slightly out of date.

From instructions to a declaration

The change that retired all sixteen pages was small to describe. Instead of writing instructions for a human to follow at each registrar, we declare once what records the service needs. Every DNS provider that has deployed that declaration already knows how to apply it. We stopped writing per-registrar logic, and we stopped writing per-registrar docs. If you want to see how a one-click connection works, you can connect a domain yourself and watch the same flow end to end.

That is the whole shift. The old approach was imperative: go here, click that, type this, then confirm. The new approach is a deterministic apply. The service states the records, the provider applies them at the source, and the customer clicks once to consent. Nobody transcribes a hostname. Nobody pastes a value into a field they had to scroll to find.

The per-customer parts still work, and they work without the customer touching them. Values that differ for each account, like an ownership verification token, are passed as variables in the redirect and substituted by the provider. The customer never sees the token, never copies it, and never adds a trailing space to it. The thing that used to generate half our failed setups simply is not something the customer handles anymore.

The maintenance profile inverts

Here is the part that mattered most to me as the person who owned that patch cycle. When a registrar redesigns its UI now, our declaration does not change. The layout of their control panel is their concern, not ours. There is no screenshot to refresh, because there is no screenshot. The trigger that used to start the whole loop just stopped firing.

The verification code got simpler in the same motion. Under manual setup, a successful check and a failed check both told you very little on their own. A missing record could be a typo, or it could be propagation delay that would resolve in an hour. You could not tell them apart, so you waited, and you guessed, and you asked the customer to look again. With a deterministic apply, a successful apply means the records are correct. There is no ambiguity to code around. The flow either succeeded, in which case the records are right, or it did not, in which case there is a real error rather than a maybe.

• No per-registrar help pages to keep current.
• No screenshot refresh when a vendor ships a redesign.
• No customer transcribing tokens or hostnames.
• No polling loop that cannot distinguish a typo from propagation delay.

What is left

The honest edge case is customers whose DNS provider has not adopted the one-click flow yet. For them we still fall back to a guided path. But that set is shrinking, and it shrinks on its own as more providers deploy the declaration. We are no longer the ones patching the long tail by hand.

When the DNS step stops being a thing your customers do and becomes a thing a provider applies, a whole category of work disappears from your queue. The sixteen help pages are gone. The verifier that guessed at other people's zones is gone. What replaced them is one file that says what the service needs, and a flow that either succeeds cleanly or tells you plainly that it did not. That is a much better thing to maintain.