Before & after
This page documents real UX writing improvements; the Before column reflects copy that existed in earlier versions of the UI. The After column reflects what's in the prototype today. If you read this page alongside the prototype, every After entry is verifiable in the running app.
Category 1: Error messages and empty states
Error messages and empty states are the highest-stakes UX copy in any product. Users encounter them when something has gone wrong or hasn't started yet. That's exactly when they need the clearest possible guidance.
1. Scan failure
| Copy | |
|---|---|
| Before | Error: Scan failed. Please try again. |
| After | Unable to reach nimbus-phoenix. Check your network connection and try again. |
Why it works: The original tells the user what happened (failure) but not why or what to do about it. The revised version names the specific system, identifies the likely cause (network), and gives a concrete next action. "Please try again" is filler, it adds no information and slightly infantilises the user.
2. Invalid system ID
| Copy | |
|---|---|
| Before | Invalid input. Please check your entry. |
| After | Must start with "nimbus-" (e.g., nimbus-lion, nimbus-phoenix). |
Why it works: "Please check your entry" is one of the most useless error messages in software. The user knows their entry is wrong, that is why they're seeing the error. The revised version tells them the correct format and gives two concrete examples. Users can fix the problem immediately without guessing.
3. Deployment blocked: Simulation not run
| Copy | |
|---|---|
| Before | Cannot proceed. Simulation required. |
| After | Run a simulation first. A passing simulation confirms the upgrade is safe to apply. |
Why it works: The original is technically accurate but provides no context. A user who doesn't remember what a simulation does won't know why this gate exists or what to do. The revised version gives a one-sentence rationale, not just the rule, but the reason for the rule. This reduces frustration and increases trust in the product.
4. API key generation: Copy warning
| Copy | |
|---|---|
| Before | Key generated successfully. |
| After | This key is shown only once. Copy it now, and store it in a secrets manager before closing this panel. |
Why it works: "Successfully" is a weak confirmation that misses the critical instruction. The key appears once. If the user closes the panel without copying it, they have to revoke and regenerate. The revised version leads with the urgent action, explains why, and gives a specific recommendation (secrets manager), all in one sentence.
5. Empty state: No systems registered
| Copy | |
|---|---|
| Before | No systems found. |
| After | No systems registered yet. Register your first system to begin the modernization pipeline. |
Why it works: "No systems found" reads as a search result, not a first-run state. It implies failure rather than an expected starting point. The revised version acknowledges the state ("yet"), frames it positively, and gives the user the single right action to take next.
6. Empty state: No active alerts
| Copy | |
|---|---|
| Before | No alerts. |
| After | No active alerts. Your systems are healthy. |
Why it works: "No alerts" is technically correct but emotionally flat. A user who sees this after a tense deployment wants reassurance, not a null result. The revised version confirms the state and adds a brief positive signal, without being verbose.
Category 2: Onboarding and tooltips
Onboarding copy sets the emotional register of the entire product experience. Tooltips are often the only documentation a user reads. Both deserve more care than they typically receive.
7. First Run Setup Wizard: Opening prompt
| Copy | |
|---|---|
| Before | Welcome to NimbusWiz. Complete the setup to get started. |
| After | Let's set up your organization. It takes about 2 minutes, and you can update these settings later. |
Why it works: The original is generic and slightly commanding. "Complete the setup" frames onboarding as homework. The revised version uses "Let's" to signal collaboration, sets an expectation (2 minutes , a real number that reduces anxiety), and removes commitment friction with "you can change everything later." Each phrase does specific work.
8. Demo Mode toggle tooltip
| Copy | |
|---|---|
| Before | Enable demo mode |
| After | Try Demo Mode to explore the platform with sample data. Your real systems are not affected. |
Why it works: The original is a label, not a tooltip. A tooltip should answer "what does this do and should I click it?" The revised version gives the benefit (explore with pre-filled data) and addresses the most common concern (will this affect my real data?) without the user having to ask.
9. Onboarding tour prompt
| Copy | |
|---|---|
| Before | Would you like to take a tour? |
| After | New here? A 3-minute tour shows you the key areas. Skip it anytime, or relaunch it from the sidebar. |
Why it works: A yes/no question puts the user in a decision-making mode at exactly the wrong moment. The revised version assumes goodwill (addressing "new here?" users directly), sets an expectation (3 minutes), and removes commitment anxiety by making both paths, take it or skip it , equally valid and equally easy.
10. Confidence score tooltip
| Copy | |
|---|---|
| Before | Confidence score |
| After | How much data the Advisor has available. Below 60% means it needs more scans or a Flight Profile to improve its recommendation. |
Why it works: The label "Confidence score" is already on the screen , the tooltip that repeats it adds nothing. The revised version explains the mechanism (data availability), gives a threshold (60%), and tells the user what to do to improve it. This turns a passive label into an actionable diagnostic.
11. Stability Index tooltip
| Copy | |
|---|---|
| Before | Stability Index: a measure of system stability |
| After | System reliability and uptime, scored 0–100. Below 50 indicates high risk; run a scan to investigate. |
Why it works: Defining "stability" as "stability" is circular. The revised version explains what's actually being measured (reliability and uptime), gives the scale range, defines the risk threshold, and suggests an action. Four pieces of useful information in one sentence.
Category 3: Button labels and CTAs
Button labels are the most constrained form of UX writing: often two to four words, and the most frequently neglected. Generic labels like "Next" and "Submit" are missed opportunities to confirm what will happen and reduce hesitation.
12. Proceed to Modernization Advisor
| Copy | |
|---|---|
| Before | Next |
| After | Go to Modernization Advisor |
Why it works: "Next" is a navigation primitive, not a CTA. It tells the user nothing about where they're going. In a multi-step pipeline where each stage has a name and a purpose, the button label should name the destination. Users who understand where they're going click with more confidence.
13. Rollback action
| Copy | |
|---|---|
| Before | Undo |
| After | Roll back deployment |
Why it works: "Undo" implies reversibility that may not be complete. It also applies to trivial actions (typing, form input) and a significant infrastructure action (deployment rollback), the same word shouldn't cover both. "Roll back deployment" names the specific action and its scope, which is what a user needs when they're about to do something consequential.
14. Register a new system
| Copy | |
|---|---|
| Before | Add New System |
| After | Register a system |
Why it works: "Add" is a generic verb that could mean anything , add to a list, add to a cart, add a user. "Register" is the specific NimbusWiz term defined in the taxonomy and used consistently in the documentation. Using the same term in the UI and the docs creates a coherent experience, users learn one word, not two.
15. Demo Mode toggle states
| Copy | |
|---|---|
| Before (active) | Demo Mode: ON |
| Before (inactive) | Demo Mode: OFF |
| After (active) | Demo mode active |
| After (inactive) | Try demo mode (your real data stays safe) |
Why it works: ON/OFF is a binary state label, accurate but cold. The active state is already clear from the blue button color; "Active" confirms it in plain language. The inactive state does something more interesting: it names the benefit ("Try Demo") and immediately addresses the most common concern ("Your Data Safe") in parentheses. It's a CTA and a reassurance in four words.
Audit summary
| Category | Examples | Primary issues in original copy |
|---|---|---|
| Error messages & empty states | 6 | Generic causes, missing next actions, neutral-to-negative framing |
| Onboarding & tooltips | 5 | Circular definitions, commitment anxiety, labels masquerading as tooltips |
| Button labels & CTAs | 4 | Generic verbs, destination-blind navigation, inconsistent terminology |