Flashcards and solutions

A flashcard is one practice item of a deck. The app schedules it with spaced repetition. A flashcard has a question, an answer, and an optional solution: the full worked answer.

A flashcard

::: flashcard q1
Solve $3x - 6 = 9$ for $x$.

::: answer
$x = 5$. Add 6 to both sides, then divide by 3.
:::

::: solution
$$ 3x - 6 = 9 \implies 3x = 15 \implies x = 5 $$

Check: $3(5) - 6 = 9$. ∎
:::
:::

Put the flashcards of a deck after its cards. The app shows them in the sets of the topic and the section.

An inline flashcard

Put a flashcard between two cards, and it is inline. The app shows it in the deck, before the next card, and the learner can answer it there. It is the same flashcard: it has one schedule, and it also shows in the sets.

::: card
A linear equation in one unknown has the form $a x + b = 0$.
:::

::: flashcard q1
Solve $2x + 4 = 10$ for $x$.

::: answer
$x = 3$.
:::
:::

::: card
The graph of $y = a x + b$ is a straight line.
:::

An inline flashcard takes no card number, so the cards after it keep their numbers. The deck is read when its cards are seen: the learner does not have to answer the flashcard for that.

The id

The word after ::: flashcard is the id of the flashcard. The id is optional. Without it, the flashcard takes e1, e2, and so on, by its position among the flashcards of the deck.

Give each flashcard an explicit id, and keep it. The schedule of the learner follows the id. Insert a flashcard without an id before the others, and every flashcard after it takes a new position. The learners then lose those schedules on the next refresh.

Keep each id unique in its deck. Two flashcards with one id are an error, and a derived id counts: a flashcard with the id e2 and the second flashcard without an id collide.

ERROR ./math/alg/linears/solving.md:13: `q1` is already the id of another flashcard in this file, at line 5: rename one

The answer

The answer is required. The checker reports a flashcard without one at its first line:

ERROR ./math/alg/linears/solving.md:9: this block has no `::: answer`: a flashcard needs its back, and a question its answer

Write the answer so the learner can check it against their own work: the result, and one line of guidance at most. Do not put the full working in the answer.

The solution

The solution is optional. It holds the full working for this flashcard. Write it as a log: one step per line, real numbers, the result with its unit, and ∎ at the end.

The solution sits beside the answer, inside the flashcard. Close the answer before you open the solution:

::: flashcard q2
Find the Thévenin equivalent the load sees.

::: answer
16 V in series with 4 Ω.
:::

::: solution
Remove the load. With the terminals open, …
:::
:::

A solution inside the answer is an error, because a block nests one level only:

ERROR ./math/alg/linears/solving.md:27: `::: solution` opens two blocks deep, and a block nests one level at most (an `answer` in a `flashcard`, a `legend` in a `reference`): close the block above it first

A solution belongs to its flashcard only. It is not a derivation: a derivation says why a reference is true, and it lives in the reference (References and derivations). Never write one as the other.

What a flashcard can hold

A flashcard holds only an ::: answer and a ::: solution. Any other block inside it is an error:

ERROR ./math/alg/linears/solving.md:24: `card` cannot sit inside `flashcard`

The question, the answer and the solution take the same Markdown as a card: prose, math, pictures from assets/, and links to references and to the figures of the deck. A link to a reference in any of the three links the flashcard to that reference.

A plot block in a flashcard is an error, because the app draws a plot only in a card or a figure. Put live plots in cards:

ERROR ./math/alg/linears/solving.md:8: a `plot` block draws only in a `card` or a `figure`, and this one sits in `flashcard`, so the app never draws it: move it to a card

How the app reviews flashcards

The app collects the flashcards of a topic from its decks. It collects the flashcards of a section from its topics, and those of a domain from its sections. One schedule stands behind all these sets, so a grade in any set goes to the same flashcard.

A run over a set shows every flashcard at once, in four groups:

The learner opens a flashcard. The app shows the question, the Answer and the Solution together, and three grades: Fail, Almost and Perfect. The scheduler is FSRS. Fail, Almost and Perfect give the FSRS ratings Again, Hard and Good. The scheduler then sets the next date of the flashcard.

So write each question so that the learner can grade it honestly:

• One question, one answer. The answer must be clear and defensible.
• No tricks. No trick wording, and no false options.
• The answer checks the work. The learner compares the answer with their own result, and grades.

Edits and progress

A refresh compares each flashcard with the version the learner holds. The question, the answer and the solution all count.

So fix a typo in an answer only when it matters: the fix clears that flashcard for every learner.

An exam writes its questions as ::: question blocks, with the same answer and solution, and the app never schedules them. Exams explains them.