DEV Community

Daniel Pertu
Daniel Pertu

Posted on

Our glossary defines Shorts and not Reels, and two regulators appear on 18 pages each without their names

Nakodo has a glossary: 27 plain definitions of the words that come up in creator sponsorships. It exists because the rest of the site uses those words, and a reader who does not know what a rate card is should not have to leave to find out.

That is a claim with two halves, and both are measurable. Are the words we define actually used? Are the words we use actually defined? I fetched the 76 public pages and counted.

Method, and the two traps in it

Take the visible text of each page with html.parser, then strip header, footer and nav before counting anything. The first version of this measurement did not, and the result was a list of our own navigation links: the top phrases across the site were "guides blog", "rate calculator" and "start free", on 76 pages each, because every page carries the same footer.

The second trap is substring counting. The word "reach" appears 251 times if you count it with str.count, and 71 times if you count it with a word boundary, because "outreach" contains it. A jargon census is a list of words that look alike, so every count below uses (?<![a-z])term(?![a-z]).

Half the glossary carries the site, the other half is barely used

Occurrences of each defined term, and how many of the 76 pages use it:

Engagement rate              362   76 pages
Disclosure                   171   41
CPM                           99   18
Median views                  96   37
Business email                89   38
Discount code                 67   18
Shorts                        63   15
Affiliate link                61   14
Link-in-bio page              55   11
Product seeding               51   24
Usage rights                  50   22
Exclusivity                   48   20
Fit score                     39   26
Media kit                     32    8
Dedicated video               31    9
Flat fee                      23   15
Micro creator                 22    6
Rate card                     21   13
Views per subscriber          20    5
Sponsorship brief             18   12
UTM parameters                14    5
Cost per acquisition (CPA)    13    2
Brand safety                   6    4
Multi-channel network (MCN)    5    1
Paid promotion label           5    4
Talent manager                 4    3
Brand integration              3    1
Enter fullscreen mode Exit fullscreen mode

Nothing in that list is wrong, but the bottom five are definitions written for completeness rather than for a reader who got stuck. "Brand integration" is defined once and used three times, all on one page. A glossary is allowed to be an encyclopaedia, and ours was clearly written as one.

The links only go one way

pages linking to /glossary (the footer does it):        76
pages linking to a specific definition, /glossary#x:    23
total in-text links to definitions:                     59
distinct anchors linked:                                22 of 27
anchors nothing links to:  business-email, engagement-rate, fit-score,
                           multi-channel-network, talent-manager
Enter fullscreen mode Exit fullscreen mode

Every page can reach the glossary and a third of them point at a definition. The five anchors nothing links to are interesting as a group: three of them ("business email", "engagement rate", "fit score") are the three most-used concepts on the whole site. They have no inbound links because they each have something better: a guide, a calculator, or a page explaining it. The glossary entry is the fallback for a term with no home of its own, and the measurement shows exactly which terms those are.

The words we use and do not define

Counting a hand-built candidate list of industry vocabulary against the glossary:

term                 uses  pages  defined
outreach              147     38  no
reels                  76     18  no
reach                  71     36  no
commission             62     22  no (it is inside the affiliate-link definition)
spark ads              60     22  no
median plays           44     20  no
paid partnership       44     14  no (we define "paid promotion label")
follower count         40     21  no
partnership ads        37     13  no
ugc                    36      9  no
fake followers         23      9  no
subscriber count       21     10  no
pitch                  19     13  no
deliverables           18      8  no
gifting                11      8  no
Enter fullscreen mode Exit fullscreen mode

Two of those stand out because of what we do define.

We define Shorts, with a link to YouTube's help page, and we do not define Reels, which our pages use 76 times across 18 pages. We define Median views, which is the number our whole pricing discussion rests on, and we do not define median plays, which is the same idea on TikTok and appears 44 times on 20 pages. The glossary even says "keep long-form videos and Shorts apart", so the asymmetry is not an opinion about platforms.

The explanation is a date. This product started as a YouTube tool and the glossary was written then. Instagram and TikTok pages arrived later, with their own vocabulary, and nobody went back. You cannot see that from reading the glossary, which looks complete. You can see it instantly from a count of what the other 75 pages say.

The acronyms nobody expands

For each acronym, how many pages use it, and how many of those spell it out at least once:

        used on   expanded on
FTC       23          1
ASA       18          0
CMA       18          0
UGC        9          1
CPM       18         10
UTM        7          5
CPA        1          1
MCN        1          1
Enter fullscreen mode Exit fullscreen mode

The bottom four are in the glossary, and the glossary entries carry the expansion, which is why those numbers look healthy. The top four are not, and two of them are regulators: 18 pages of ours mention the ASA and the CMA, and not one of them says Advertising Standards Authority or Competition and Markets Authority.

These appear on our disclosure rules pages, which exist precisely so a reader who does not know the rules can follow them. Telling that reader to check "the ASA" is telling them to search for an acronym. This is the clearest finding of the whole exercise and it is six words of copy per page.

What I am changing

  1. Four new definitions: Reels, median plays, Spark Ads and partnership ads, UGC. All four are already used on a dozen pages or more.
  2. Expand ASA, CMA and FTC on first use, on every page that names them. Then a test: a list of acronyms that must be expanded somewhere on any page that uses them, checked over the rendered text rather than the source, because the rendering is where a reader meets it.
  3. The glossary keeps its five unlinked entries. Three of them are unlinked because the concept outgrew the glossary, and that is the system working.
  4. The jargon census becomes a script in the repo, run before publishing a new batch of pages. Not a test: a list of words a human should look at, because "a word that appears on twenty pages and is defined nowhere" is a judgement, not a failure.

Top comments (0)