How cards are written

A card holds one idea and finishes. You should be able to read one, close the tab, and have learned something whole, not a fragment that only pays off three cards later.

That is why most cards take about a minute. It is the only honest thing to offer someone who has ten minutes and no guarantee of the eleventh.

A card says why an idea exists before it says what the idea is.

Being handed a definition you have no use for yet is work with no reward, and it is where most people stop reading. So a card opens on a situation you might recognise (something that broke, something that behaved oddly, a choice you have to make) and the definition arrives once there is somewhere to put it.

If a card reads like a dictionary entry, it is one we have not finished writing.

An idea shown once tends to be learned as that one instance. You recognise it again in the same clothes and miss it everywhere else.

So where an idea has to travel, where you will meet it in code that looks nothing like the code here, you get two examples that share the structure and differ in everything else, and a line saying what the two have in common. That comparison is what makes an idea portable, and it is why some topics are longer than they first look.

You might arrive at any card from a search result, a bookmark, a link someone sent you, or your review queue. None of those start at the beginning.

So no card says "as we saw above". Each one makes sense where it stands and says what it assumes, with a link to whatever it builds on. The order of a topic is still deliberate, so following it helps, but nothing breaks if you do not.

Every card is labelled with the kind of thing it is, so you can tell at a glance what you are about to read.

• Concept — one idea, introduced and made usable.
• Example — that idea, attached to something real.
• Walkthrough — a process, start to finish, in the order it happens.
• Comparison — two or more options on the same axes, and when each one wins.
• Gotcha — a specific surprise: the symptom, why it happens, and what to do instead.
• Code — a listing that is itself the thing worth reading.
• Exercise — something to try or predict, with the answer a click away.
• Recap — what a topic established, for when you come back to it.

Before a topic is written, we decide what you should be able to do at the end of it, and we draft the questions that would show it. Only then do the cards get written.

The other order produces a quiz that tests whether you read the page. This one means the cards have to earn the questions, and a question with no card behind it is how we find the card we forgot to write.

Nothing is scored, and nothing that identifies you is kept. Answers are checked on the server, so the page never carries them, and your review queue lives in your own browser and never leaves it.

A wrong answer does one thing. It puts that question back in your queue: tomorrow, then a few days later, then further apart as you get it right. Spacing questions out like that is one of the most reliable findings there is about remembering, and it beats rereading the card.

Every wrong answer explains itself: why the option you picked was tempting, what separates it from the right one, and which card covers it.

Questions also tell us when a card has failed. Anonymous, aggregate counts of how each question performs are the point. A question almost everyone gets wrong is usually not a hard question; it is a card that did not do its job.

It has to carry one idea, open on a situation rather than a definition, ground anything abstract in something concrete, make sense to someone who arrived at it cold, say what changes now that you know it, and carry a title that tells you what is on it.

Anything that is true but not teaching gets cut.

Some of this will be wrong, and some of it will go out of date. Tell us. A correction is worth more to the next reader than anything else you could send.