DEV Community

Daniel Pertu
Daniel Pertu

Posted on

Our desktop app's whole interface is 485 words, our website is 35,841, and the 23 words only the app knows are all about things going wrong

Notifio is two codebases that have to agree with each other: an Electron app that does the work on your machine, and a Next.js site that explains and sells it. I have measured plenty of ways they disagree on numbers, like 33 of our 38 pages saying we check every 30 seconds and 25 of them promising no limit on something the app caps at 15.

This time I wanted the words rather than the numbers. Does the product speak the language its own marketing taught the reader?

The two corpora

The app side is every string a user can read in the renderer: JSX text nodes and quoted copy across the 13 .tsx files that make up the window.

renderer .tsx files                        13
distinct user-visible strings             113
mean string length                       24.2 characters
longest string                             77 characters
word tokens                               485
distinct words                            195
distinct content words (stop words out)   153
Enter fullscreen mode Exit fullscreen mode

The site side is the visible text of all 38 URLs in the sitemap, with script and style content stripped:

word tokens      35,841
distinct words    2,877
Enter fullscreen mode Exit fullscreen mode

Seventy-four times as many words to sell the thing as there are inside the thing. I knew the app was terse, because its status lines are one word each by design and six of its numbers are deliberately not a settings screen. I did not know it was 485 words terse. The entire interface of a paid product fits in a third of this blog post.

The overlap is good

app content words that also appear somewhere on the site   130   (85%)
app content words that appear on none of the 38 pages       23
Enter fullscreen mode Exit fullscreen mode

Eighty-five per cent is better than I expected from two codebases with no shared string table and no copy review between them. The shared half is the vocabulary you would hope for: search, site, listing, reply, session, token, monitor, email.

The direction of the imbalance is the interesting part though. Here is how often each side uses the nouns they share:

word         app UI    site
alerts            1     431
rental            0     156
monitor           2     155
portal            0      63
search           14     248
sites             2     235
listing(s)        5     204
finds             2       5
Enter fullscreen mode Exit fullscreen mode

The site's single most used noun is "alerts", 431 times, and the app's interface says it once. "Rental" is on the site 156 times and is not in the app at all, which is defensible: by the time you are in the window you know what you are looking for. "Portal" appears 63 times on the site and never in the product, and that one is a marketing word that leaked into our own documentation.

The reverse case is "finds", our word for what the app has caught. The window has a Latest Finds panel. The site says "finds" five times and "listings" 204 times. The thing a reader has been trained for 204 repetitions to call a listing is labelled something else the moment they pay.

The 23 words the site has never heard of

baseline, cleared, confirmation, context, emailed, escape, failed,
invalid, latest, loading, meanwhile, opened, pause, press, redo,
reset, resetting, retry, sections, switched, unknown, untested, verifying
Enter fullscreen mode Exit fullscreen mode

Read that list as a group and it is not a random sample of the app's vocabulary. It is failure, waiting and undo: failed, invalid, unknown, retry, verifying, loading, resetting, cleared, redo, pause. Those are the words a product uses when it is not succeeding, and a marketing site is written entirely in the voice of things succeeding. Thirty-eight pages, 35,841 words, and not one of them is "failed".

That is a tone problem on the site and a support problem in practice. I checked whether the exact strings the app shows when something is wrong appear anywhere we publish:

string the app can show        pages of 38 containing it
"License invalid"                                      0
"Not activated"                                        0
"Activation failed. Please try again."                 0
"Could not start checkout"                             0
"Not set up"                                           0
"Site changed"                                         0
"Find history cleared"                                 0
the bare words invalid / failed / retry                0
"activation token"                                     5
Enter fullscreen mode Exit fullscreen mode

A user whose app says License invalid and who does the obvious thing, searching our site or the web for that phrase, finds nothing of ours. Our help page answers six questions, one of which is about a lost activation token, and that is the only place where the unhappy path is written down at all. Our 125 FAQ questions across 30 pages are all about what happens when things work.

What I am doing with this

Three changes, in the order I believe in them:

  1. Put the app's error strings on the help page verbatim, each with the two or three things that cause it. This is cheap, it is honest, and it is the only version of this that helps somebody at 11pm with a window that says License invalid. Verbatim matters: the string has to be greppable, so it should be the same characters the app renders, not a paraphrase.
  2. Settle on "listings" everywhere, including in the window. We have one word on the site used 204 times and a different word in the product used twice, and the product should lose that argument.
  3. Leave the 485 words alone. The temptation when you measure a UI this small is to pad it, and the app's terseness is the reason a window can say what it is doing in one line.

The measurement itself is about fifty lines of regex over the renderer plus a text extraction of the live pages, which means it can be a test rather than an essay: fail the build if a user-visible string in the app contains a word that appears nowhere on the site. I am not going to write that test yet, because today the answer it would give is twenty-three words long and every one of them is correct.

If you want to see both halves, the words that sell it are on notifio.app and in the guides, and the words inside it are in a window you get from the download page. There are far fewer of the second kind than you would guess.

Top comments (0)