Why developer-written help creates support tickets
Your product has help text. Tooltips, empty states, the paragraph above the tricky form. It was written by the developer who built the screen, in the same pull request, some time after five o'clock. It is accurate. It is also the reason for a recognisable class of support ticket.
This is not about developers writing badly. Plenty write well. It is about who can and cannot see the confusion.
The problem is knowledge, not skill
To build the screen, the developer had to understand the rules behind it. By the time the text gets written, that understanding is complete, and it cannot be switched off. Everything on the screen now looks self-evident, because it is self-evident to the only person in the room.
So the text answers the question that is still interesting to the author, which is what the thing is, and skips the ones the user actually has, which are what to put in it, what happens next, and whether it can be undone.
What that looks like in the product
The label, restated. Above a field called Billing interval: "Select the billing interval." Correct, and it adds nothing. The user did not fail to read the label. They do not know which interval is right for them.
The internal noun. The code calls it an entity, the interface calls it a record, and the help text uses both. The user now believes there are two things. Most of these tickets open with "what is the difference between".
Mechanism instead of decision. "Entries are resolved against the active snapshot." True, and it explains how your system works to someone who wanted to know whether their change is live yet.
No consequence. The text says what the button does and not what it costs, who can see the result, whether it sends mail, or what happens to the data that was there before. Almost every ticket that starts "I clicked it and now" is a missing consequence.
Written once, at the worst possible moment. The text is created when the feature is newest, before anyone has used it, and then never revisited, because changing a sentence means a pull request, a review and a release. The confusion arrives in month three. The text stays at week one.
Who should write it
The person who sees the questions. Support, a technical writer, a product manager who reads tickets. Not because they write more elegantly, but because they still remember what it is like not to know, and because they hear the same sentence twenty times before anyone else hears it once.
That does not remove the developer from the loop. The good arrangement is two roles:
- The developer supplies what is true. What the system actually does, which cases exist, what is reversible, what the limits are.
- The other person supplies what the user needs to decide. The order, the words, the consequence, the thing worth warning about.
Then the developer checks the result for accuracy, which takes two minutes, instead of writing it from scratch, which takes twenty and produces a worse text.
The part that is a tooling problem
Even when everyone agrees who should write the help, one thing usually stops it: the text lives in the repository. Whoever wants to improve a sentence needs a branch, a review and a deploy, and a developer to do all three. So the improvement gets filed as a low-priority task, and the tooltip that generates four tickets a week stays exactly as it is.
That part is fixable without changing anyone's job. When help text is content that a person can publish on their own, the correction happens the same afternoon as the ticket that prompted it. How to manage in-app help sets out the levels that run from strings in your repository to content someone publishes alone.
When the developer is the right author
For developer-facing products, the person who knows the system is usually also the reader's closest peer. API documentation, error codes, integration notes: an engineer who writes clearly is the best author you can get, and handing that to someone who has never made the request produces worse text.
The rule is not "developers should not write help". It is that the author should share the reader's starting point, and for most in-product help, the reader starts without the model in their head.
Where to start
Do not rewrite the help text. Start from the questions, in the order in which they cost you the most. Turning support tickets into in-app help is the method, including the part where every answer gets checked against the product before it goes live.