This page is for anyone curious about how a term is put together, or planning to add their own. A term can be a word from a field, or a word, phrase, or grammar construction in a language you're learning.
You can paste a list from Notes or a spreadsheet, bring a deck from another app, import JSON from an LLM prompt I prepared for a field or a language, or add terms one at a time. Only the term itself is required. A term without a definition waits in your collection and stays out of Read, Review, and Quiz until you add one.
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 or a textbook, but not to use it in conversation.
I also had a passive memory problem. I'd read a definition, feel like I had it, and forget it a week later. Or I'd recognize the word when someone else said it and draw a blank when it was my turn to use it.
Two problems kept coming up: shallow understanding, where I could repeat a definition but not apply the word, and mixing terms up, like coupling and cohesion. What I wanted was an example, how people actually use the word, 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. Recognizing it on a slide isn't enough.
What goes in a term
A term is worth keeping once it has a name, a category, and a definition. The optional fields below are what separate 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.
- Mental model: optional. A comparison or analogy, a way to think about the term rather than what it does. Add it when it would make the term click faster than the definition alone.
- 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.
- Anti-example: optional and rare. A near-miss, something that looks like this term but isn't, so you can tell them apart. Only when there's a real risk of confusing the two.
- Debated: optional and rare. Only when practitioners genuinely disagree on meaning or scope, not loose usage, not a caution about overuse.
- Note: optional. Freeform text for something that doesn't belong in the other fields. What it holds is up to the collection. Empty means not needed.
- 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
An empty optional field means "not needed", not "to do". 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.
- Mental model: a comparison or analogy would make this click faster than the definition 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.
- Anti-example: there's something people commonly mistake for this term, and naming the difference would help.
- Debated: people in the field actually disagree on what this term means or how far it extends.
- Note: there's something about this term that doesn't belong in the other fields.
- Relationships: this term connects to another one in a way worth naming: confusion, dependency, contrast, or otherwise.
Known and unknown
You don't set "known" by hand. It's worked out from how well you've retained the term: how much you've read it, how you've done recalling it in Review, and how you've done recognizing it in Quiz. All three fade if you stop practicing, so the badge shows where you are right now rather than a status you set once and forget.
Read, Review, and Quiz all draw from the same terms, each ranked by what you're most at risk of forgetting in that mode. There's no separate pool of known terms to graduate into. A term you haven't touched in a while can come back in any of the three, and only a strong run of practice moves the badge.
When a term is done
A term is done when I could use the word correctly in conversation, whether or not every optional field is filled. I go back to a term when I meet it in the wild and notice something 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 you could use the word.