Framework
Language that gets the job done
Users think about their tasks, not how the system works.
When I led a large-scale navigation overhaul, the changes were not made lightly. It was critical that we conducted statistically significant user research to feel confident in our decisions. And when I was analyzing the results and reading hundreds of pieces of open-ended feedback, one thing became very clear:
Users think about their tasks, not how the system works.
They log into a dashboard with defined goals. And they are not necessarily approaching those goals with technical models in mind either. In fact, the research found that many users were much less technical than internal teams often assumed. When trying to find where in the dashboard to complete those goals, they were simply scanning for keywords or tools that could help get the job done.
Or as one user put it:
"I swear to God, I don't understand anything. I really need a VPN."
I realized that it was not just our side navigation that needed language updates. Almost every piece of instructional content in the dashboard should be audited to see if it focuses only on the how, or what really matters: the why.
An illustrative example
Take this example of a label for one of the WARP client settings:
Override local interface IP
Assign a unique IP Address to each WARP device. This address will be randomly selected from the Carrier Grade NAT space (i.e. 100.64/10) and will override the existing local interface IP.
The label "Override local interface IP" is accurate. It explains what WARP will do when users toggle it on. But to most users, it is a wall of how language that requires additional explanation to understand what it means and why they would want to use it.
And while the description of the setting does explain the outcome, we are heavily burying the lede. Now imagine we reframed the label to feature the why:
Assign a unique IP address to each device
Override the device's existing local interface IP with a unique IP address randomly assigned from the Carrier Grade NAT space (i.e. 100.64/10). This setting is on by default for devices using MASQUE and required to create tunnels with the WARP Connector.
This way, users only need to read one line to know what they can achieve. Based on that, they can decide if they care about the how.
Labels are for outcomes
They should be scannable and self-explanatory.
Descriptions are for details
This is where we can give additional context on the how for users who want to learn more.
When we lead with the action and support it with concise, optional context, we meet users where they are, regardless of whether they want to click and move on or dive deeper.
Why this matters
If we lean on implementation-oriented terms, we are asking users to guess what the practical outcome is. That can be intimidating. The more we use outcome-oriented labels, the more confident users feel in their actions, and the more they trust us.
Outcome-based language:
Guides users to the right action quickly
Reduces friction and hesitation
Builds confidence without requiring a deep technical background
Increases adoption of features that might otherwise be overlooked
Of course, there are still users who are deeply interested in understanding the how, and that is where documentation becomes extraordinarily valuable. Technical documentation can go deeper, offering the nitty gritty details and architectural explanations while the UI clarifies the immediate path forward.
Tips for improving
Here are some questions anyone can ask themselves when writing content for the UI:
Frame around the goal
Make sure the outcome of creating an object or turning on a setting is clear.
- What is the user trying to do?
- Would a user say out loud, "I want to [insert your label]"? If not, reframe to match how someone might describe the goal in plain language.
Watch out for how language
Avoid describing what we built or how we built it when the user first needs to understand what they get from it.
- Are you describing what the system is doing, or what the user gets from it?
- Could this label be understood without deep technical knowledge?
Behind every feature is great technical work. But while the tech makes it possible, it is the language that makes it usable.