Most "users don't understand the product" problems are not comprehension problems. They are notation problems: a name that invites a wrong inference, a symbol whose meaning is set by somebody else's community, a primitive doing five jobs under one label, a table whose uniform typography promises a reliability you do not have.
This skill covers the part of the work that happens in names, symbols and reference material — before the user acts, not during. It owns what a symbol means, not how it is drawn, and not what the interface says back the moment something goes wrong.
Scan the descriptions, follow only the [[wikilinks]] you need.
Designing the notation
- [[references/redesign-the-notation-dont-scale-the-training]] — training cost is paid per user forever; when adoption is blocked by learning cost, change the notation, and let a fluent user design it.
- [[references/motivated-form-and-one-symbol-one-thing]] — make each element's form encode what it does, and hold one symbol to one meaning (but only for distinctions users act on).
- [[references/name-the-category-for-what-it-does]] — users reason forward from names; regular compositional names are one rule instead of N facts.
- [[references/split-one-overloaded-primitive-into-named-senses]] — when one thing does five jobs, refuse the unifying definition and document five trigger conditions.
How users actually receive it
- [[references/near-matches-are-more-dangerous-than-unknowns]] — familiarity suppresses checking, so the near-miss is the silent error and the alien token is the easy one.
- [[references/users-snap-the-new-thing-to-categories-they-already-have]] — anything falling between two of a user's existing categories gets rounded to one, silently.
- [[references/meaning-mutates-when-a-term-crosses-a-boundary]] — the receiving team re-reads your term as a modifier, then generalises it somewhere you never meant.
- [[references/your-symbol-set-is-not-a-shared-language]] — a large minority reads any symbol with a different or opposite valence, and cannot tell that they did.
Writing the reference material
- [[references/ship-a-labelled-default-with-named-exceptions]] — label the coverage boundary instead of shipping a false universal or a useless hedge; tier inside the document.
- [[references/teach-the-invariant-the-exception-preserves]] — find what an exception is protecting and teach that; name the arbitrary residue as arbitrary.
- [[references/mark-only-what-deviates-and-force-the-unambiguous-form]] — flag exactly the unreliable rows, and where conventions collide, refuse to emit the ambiguous form.
- [[references/document-the-failure-not-just-the-answer]] — enumerate the real failure modes with recovery cues, attach limits inline, and name the false belief rather than the right answer.
- [[references/teach-a-choice-with-a-minimal-contrast]] — hold everything constant but the deciding variable; index by the decision, not by your taxonomy.
Where to start
- Users keep making the same mistake → [[references/document-the-failure-not-just-the-answer]], then [[references/near-matches-are-more-dangerous-than-unknowns]].
- You are naming something new → [[references/name-the-category-for-what-it-does]], then [[references/motivated-form-and-one-symbol-one-thing]].
- A doc keeps being wrong in the field → [[references/ship-a-labelled-default-with-named-exceptions]], then [[references/mark-only-what-deviates-and-force-the-unambiguous-form]].
- Onboarding keeps getting longer and adoption does not move → [[references/redesign-the-notation-dont-scale-the-training]].
Sibling skills
- [[../duo-voice/SKILL]] — the wording layer. This skill decides what a thing is called; that one decides how the product talks about it, including live error copy.
- [[../duo-design/SKILL]] — the visual layer. This skill owns what a symbol means; that one owns how it is drawn, animated and shown on screen.
- [[../duo-product/SKILL]] — whether the concept should exist at all, before you name it.
- [[../duo-experimentation/SKILL]] — how to test whether a renaming or a restructured reference page actually moved behaviour.
Sources
blog.duolingo.com — writing-system history (Hangeul, Cherokee, Adlam), the IPA, Cyrillic and false cognates, Japanese loanwords, Spanish se, preterite spelling changes, accent marks, tú/usted, demonstratives, French question structures, German gender, double names, the Duolingo/Slack emoji survey, and the calendar and pronunciation guides. Every claim carries a dated citation inside its node.