How terms are built

Why not just a definition

Flashcards and glossaries gave me the word and a one-line meaning. That was enough to recognize it in a slide deck, not enough to use it in conversation.

I also had a passive memory problem: I'd read a definition, feel like I got it, and forget it a week later. Or recognize the word when someone else said it but draw a blank when it was my turn to use it. The definition was going in, but it wasn't sticking in a way that actually held.

Two problems kept showing up: shallow understanding (I could repeat a definition but not apply the word) and mixing terms up (coupling vs cohesion, that kind of thing). What I kept wanting was an example, how people actually use it, where they disagree, and how it connects to nearby terms, so I split those into separate fields instead of cramming everything into the definition.

A term is “known” when I could define it, use it correctly, and spot misuse or nuance, not just recognize it on a slide.

What goes in a term

Every term needs a name, category, and definition, the minimum before it's worth keeping. I import lists or add terms one at a time into collections. This structure is the main thing that separates it from a one-line flashcard.

Term: The word or phrase. Keep it short.
Category: A browse label so the list doesn't turn into one blob, Architecture, Testing, whatever helps you find things later. Not a learning field.
Definition: What the term means, in plain language. Required. Meaning only, not when to use it, not how people disagree, not how it differs from a related term. If you can't say it simply, you probably don't have it yet.
Example: Optional. Add when the definition alone wouldn't let you use the word. A concrete scene (where you've seen it apply) or a natural sentence (the word used in speech), whichever makes it click.
In practice: Optional. Tradeoffs, team conventions, when you'd reach for it, usage nuance that isn't obvious from the definition. Common misuse fits here too, as does a caution about overuse, not in Debated.
Debated: Optional and rare. Only when practitioners genuinely disagree on meaning or scope, not loose usage, not a caution about overuse.
Relationships: Optional links to other terms in the collection, often confused with, depends on, builds on, opposite of, or any real connection worth pointing out. Add a line on how they differ when it helps.

When to add optional fields

Empty optional fields mean “not needed,” not “TODO.” I add a field only when it would have helped me understand or use the word.

Example: The definition is solid but I still couldn't use the word in conversation from it alone.
In practice: There's a tradeoff, convention, or "when you'd reach for it" that the definition and example don't cover for me.
Debated: People in the field actually disagree on what this term means or how far it extends.
Relationships: This term connects to another one in a way worth naming, confusion, dependency, contrast, or otherwise.

Known and unknown

Every term is either something I already knowor something I'm still learning. That split is the term's state, not a queue setting. I kept mixing known and unknown terms in one deck and wasted time on words I didn't need, so the two never mix now.

Mark a term known or unknown anywhere, in review, a quiz, the collection list, Telegram, or the desktop widget, and it moves between states. I wanted that to follow the term everywhere. Review and quizzes always draw from one pool or the other. How the smart queue works covers how the queue ranks terms inside each pool.

When a term is done

Done means I could use the word correctly in conversation, not that every optional field is filled. I revisit terms when I encounter them in the wild and realize something is missing.

What this is not

Not a wiki article, a few focused lines beat a long write-up
Not a strict taxonomy, categories are browse labels, not a learning hierarchy
Not every field on every term, leave optional ones empty
Not complete when all fields are full, complete when the use test passes