Are you still hardcoding help texts?

· Robbert

Open the file where your interface strings live. Somewhere in it is the sentence a user reads when their payment fails, or when their upload is too large, or when they land in your product for the first time and nothing is there yet. Read it out loud.

Most teams find three things at once. The sentence is longer than it needs to be. It was written by whoever built the feature. And nobody has looked at it since.

That is not a writing problem. It is a location problem.

What the location decides

Where a sentence lives decides who is allowed to change it, and how long that takes.

A string in your codebase can be changed by people with commit access, which in practice means your developers. The change needs a branch, a review and a release. That is a reasonable amount of ceremony for logic. For a sentence, it is the reason nothing gets fixed.

The cost is not the five minutes of editing. It is everything around it: noticing the problem, writing it down somewhere, waiting for it to be picked up, explaining what you meant, reviewing the result, and then waiting for the next deploy. A support agent who knows exactly what the message should say is six steps away from changing it. So they write a macro in the help desk instead, and your product keeps saying the wrong thing.

The test

Take one sentence in your product that you know is wrong. Not badly wrong, just not right: a word your users do not use, a tone that does not match, an instruction that skips a step.

Now answer two questions.

  1. Who can change it without asking anyone?
  2. How long until a user sees the new version?

If the first answer is a developer and the second is measured in days, your help text is code. It will be maintained with the care code gets, which is to say it will be maintained when it breaks the build.

What changes when the text moves out

Give every explanatory string an address. A tooltip, an error message, an empty state, an onboarding step: each gets a key, and your app asks for that key when it needs it.

Three things follow from that, and none of them are about writing better copy.

The person who knows becomes the person who changes it. Support sees the confusion first. Product knows what the feature is for. Neither of them needs to open an editor they cannot use.

A fix ships when it is written. Your app requests the current version, so publishing is the release. No branch, no review queue, no waiting for Thursday.

The text stops being invisible. When all of it sits in one place, you can read it as a whole. That is usually the moment someone notices that three screens explain the same concept in three different ways.

What it costs

A one-time integration. Your developers replace hardcoded strings with a call that fetches by key, and after that they are out of the loop for good. A coding agent can do most of the extraction: it reads your codebase, collects the explanatory strings, and hands you a file with each string, its address, and where it sat in your code.

The honest part: your app still decides where help appears and what it looks like. Nothing renders itself inside your interface. That is a deliberate limit, and it is also why there is no counting of your users and no widget that ships its own styling.

Where to start

You do not have to move everything. Start with the ten sentences your support team explains most often, which are also the ten your users meet when something has gone wrong. Give those an address, publish them, and change one without opening your editor.

That is the whole demonstration. Either a sentence in your product can be fixed by the person who noticed it, or it cannot.

Blog