Skip to content

SWI-11363 copy: replace "Blocker" with "No direct equivalent" - #25

Open
kshahbw wants to merge 3 commits into
mainfrom
chore/soften-blocker-wording
Open

SWI-11363 copy: replace "Blocker" with "No direct equivalent"#25
kshahbw wants to merge 3 commits into
mainfrom
chore/soften-blocker-wording

Conversation

@kshahbw

@kshahbw kshahbw commented Aug 20, 2026

Copy link
Copy Markdown
Contributor

BLUF

Renames the third compatibility tier from "Blocker" to "No direct equivalent" in every user-facing label. To a developer, "blocker" reads as "requires some dev work" — but to a non-technical reader it lands as a red flag about Bandwidth's capabilities. The tier actually means something narrower and more neutral: this Twilio verb has no BXML counterpart, so it needs a redesign rather than a translation.

Feedback from an internal enablement session.

Why this wording

The tool already had softer vocabulary for exactly this concept and only used "Blocker" in a few leftover spots:

  • web/view-model.ts — the pill for this bucket already reads "No equivalent"
  • web/app.ts:93 — the summary sentence already reads "…have no direct equivalent"

So this aligns the remaining labels with wording the UI was already using, rather than inventing a euphemism. It also stays honest: verbs in this bucket (Enqueue, Queue, Client, Pay) have no Bandwidth primitive at all, and "no direct equivalent" says that plainly. Softening further would have undercut the fail-loudly-never-silently promise in the README.

The 🛑 section emoji stays. The word was the problem, not the icon — a loud stop sign still matches how the rest of the tool signals "this one needs a human."

Scope: display strings only

Internal identifiers are deliberately untouched — the Bucket union member, counts.blocker, the blockers array, and coverage.json's blockers key all stay as-is, so nothing parsing the machine-readable output breaks.

Surface Change
Playground Tile label and section heading
Compatibility Check report Section heading + score-formula text
BXML Generator report Section heading + document summary line
README, web/README.md The works-as-is / heads-up / blocker triad

Before / after

- **Migration complexity: 4/10** (1 + warnings + 3×blockers, capped at 10)
+ **Migration complexity: 4/10** (1 + heads-up + 3× no-equivalent, capped at 10)

- ### 🛑 Blockers
+ ### 🛑 No direct equivalent

  - **Enqueue** — Bandwidth has no queue primitive; contact-center queue
    flows cannot be translated. ([docs](…))

Verification

  • npm run typecheck — clean
  • npm test303/303 passing
  • npm run playground:build — 4 occurrences of the new label in the built HTML, no stale Blocker labels
  • Rendered both reports against a TwiML doc containing <Enqueue> to confirm the new headings and summary line read correctly in context

Reviewer notes

  • Expect a one-line conflict with SWI-11363 chore: replace "adapter" with "translator" throughout #24. Both PRs touch examples/full-pv-app/server.js:4. Whichever merges second needs the trivially-merged result: // clean through the translator: nothing lacking a direct equivalent, only expected heads-up notes.
  • No test asserted on any of these display strings, which is why the suite stayed green. That's a pre-existing coverage gap in the report renderers — happy to add assertions if you'd like them pinned.
  • The playground pill still says "No equivalent" rather than the full "No direct equivalent", kept short because it's a space-constrained badge. Easy to align if you'd rather they match exactly.

🤖 Generated with Claude Code

"Blocker" reads to a developer as "requires some dev work," but to a
non-technical reader it lands as a red flag about Bandwidth's capabilities.
The tier means something narrower and more neutral: this Twilio verb has no
BXML counterpart, so it needs a redesign rather than a translation.

The tool already had softer vocabulary for exactly this concept — the
playground pill says "No equivalent" and its summary line says "have no
direct equivalent" — so this aligns the remaining labels with wording the
UI was already using.

Display strings only. Internal identifiers (the Bucket union, counts.blocker,
the blockers array, coverage.json's blockers key) are untouched, so nothing
parsing the machine-readable output breaks.

- Playground: tile label and section heading
- Compatibility Check report: section heading, score-formula text
- BXML Generator report: section heading, document summary line
- README, web/README: the works-as-is / heads-up / blocker triad
- Section emoji 🛑 -> 🔧, so the icon de-escalates with the word
@kshahbw
kshahbw requested review from a team as code owners August 20, 2026 18:47
@bwappsec

bwappsec commented Aug 20, 2026

Copy link
Copy Markdown

Snyk checks have passed. No issues have been found so far.

Status Scan Engine Critical High Medium Low Total (0)
Open Source Security 0 0 0 0 0 issues
Licenses 0 0 0 0 0 issues
Code Security 0 0 0 0 0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

@kshahbw kshahbw changed the title copy: replace "Blocker" with "No direct equivalent" SWI-11363 copy: replace "Blocker" with "No direct equivalent" Aug 20, 2026
The word was the problem, not the icon. "No direct equivalent" already
reframes the tier as a difference rather than a verdict on Bandwidth, and
a loud stop sign still matches how the rest of the tool signals "this one
needs a human." Reverts the 🔧 swap from the previous commit.
joshraub-bw
joshraub-bw previously approved these changes Aug 20, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants