chore: trim keywords from 37 to 10, reversing the expansion - #22
Merged
Conversation
The expansion two releases ago pushed the wrong way. Measuring the 'nuban' result set (n=14 packages all carrying the term in their description), search score correlates NEGATIVELY with keyword count (-0.24), description length (-0.30) and how late the term appears in the description (-0.29) — the signature of TF-IDF field-length normalisation. Every extra keyword dilutes the ones that matter. For scale, #1 'nuban' carries 2 keywords and a 47-char description; we carried 37 and 186. No measured harm was done (nuban was #8 before the expansion and #8 after), so this is a course correction, not a bug fix. Kept the ten terms that measurably rank or are high-intent: vnin (#1), rsa-pin (#2), bvn (#3), naija (#5), nuban (#8), nin (#10), cac (#20), tin (#29), plus tax-id and nigeria. Dropped 27 that returned NO ranking when tested directly — kyc, pii, redaction, identity, e164, msisdn, phone, plate, passport, validation, validator and the spelled-out variants. They sit in crowded generic fields where name-token matching decides the outcome, so they contributed dilution and nothing else. Description deliberately unchanged: front-loading identifier names would improve term position, but it is the human-facing line on the npm page, and trading readability for a couple of positions on a query where the exact-name package outscores us 13x is a bad deal.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This reverses most of what I did in 0.5.2. The measurement says I pushed the wrong way.
The evidence
For the "nuban" result set — 14 packages that all carry the term in their description, so name-matching is held roughly constant — search score correlates negatively with every field-size metric:
And we were the outlier on all three:
That is the signature of TF-IDF field-length normalisation — a standard search behaviour. Every extra keyword dilutes the weight of the ones you care about. Adding 15 keywords to improve discoverability was exactly backwards.
No harm was actually done:
nubanranked #8 before the expansion and #8 after. So this is a course correction, not a bug fix.What's kept — the ten that earn their place
Tested each keyword directly against the search API:
vninnubanrsa-pinninbvncacnaijatinPlus
tax-id(the current NRS identifier — high intent, no ranking data yet) andnigeria(country term, appears in the multi-word queries).What's dropped — 27 that returned nothing
Every one of those returned no ranking at all when queried directly. They sit in crowded generic fields where npm's name-token matching decides the outcome — so they contributed dilution and nothing else.
Description deliberately unchanged
Front-loading the identifier names would improve term position (
nubancurrently sits at character 133 of 186). I'm not doing it: the description is the human-facing line on the npm page and in GitHub search results, and trading readability for a couple of positions on a query where the exact-name package outscores us 13× (1059 vs 82) is a bad deal.Two honest caveats
nubanfeat: generator parity — every identifier gets a generate* counterpart #8 → maybe feat: Nigerian Tax ID, vNIN, NCC prefix refresh, legacy bank codes #5–6. Worth doing because it costs nothing and is invisible to readers, not because it's transformative.On releasing
Changeset is
patch. I'd suggest merging this but letting the Version Packages PR sit until there's something else worth shipping — this would be the third patch release today for metadata alone, and the ranking gain doesn't justify burning another version on its own.