Writing Mathematical Questions

A math question in DoenetML is just an <answer> with the correct expression inside it — type the answer, and Doenet grades whatever the reader enters, accepting any mathematically equivalent form by default. This guide starts from that one-line version and then walks through the attributes and children that change how the answer is graded: accepting several answers, awarding partial credit, requiring an exact form, allowing rounding, checking a list of values, and letting Doenet compute the answer key. Each section shows a live example — editable source beside its result — and explains what it actually does.

It assumes you already know the basics of writing DoenetML — tags, attributes, and children. For the complete list of every attribute and property, see the <answer> reference pages. See Advanced Mathematical Questions for a follow-up guide.

The simplest version

Put the question in a <label> and the correct answer in an <award>. That is the whole recipe.

A few things are worth noticing:

• The <label> is the question; the <award> is a correct answer. Because the <answer> has no input of its own, it creates one automatically, and the <label> both displays the prompt and ties it to that input so a screen reader announces the question.
• For a single answer, the <award> is optional. Writing the value as bare math does the same thing — <answer><label>…</label>2x</answer> — but spelling it out with <award> is the form every section below builds on. Either way, keep the <label>: <answer>2x</answer> works but leaves the input unlabeled.
• Doenet accepts any equivalent form. By default a math answer uses a numerical checker with a liberal notion of equality, so 2x, x + x, and 2*x are all marked correct. The sections below show how to tighten that up.

When the question is part of the sentence

If the surrounding text already asks the question, a visible <label> would only repeat it. Drop the <answer> into the sentence and give it a <shortDescription> instead — invisible on screen, but read aloud so the input is not announced as an unlabeled control.

Accept several correct answers

One <award> accepts one response. Give the <answer> several and any of them counts as correct.

Each <award> holds one acceptable response. When the reader matches any award, they earn its credit (full credit, here).

Give partial credit

Add a credit attribute to an <award> to grant a fraction of the points for an incomplete answer.

Here the full antiderivative earns full credit, while forgetting the constant of integration earns half. If several awards match, Doenet credits the highest-scoring one. (Note that C is a specific symbol — a reader who writes + K is not equivalent, so add more awards if you want to accept other letters.)

Show targeted feedback

To respond to a specific wrong answer, give that <award> a name, then add a <feedback> whose condition references the award. When the award matches, the feedback appears wherever you placed the <feedback> block.

Submit 20 (multiplying instead of dividing) and the feedback appears; submit 5 and it doesn’t. The <award credit="0"> grants no credit — it exists only to recognize the mistake and trigger the message.

For feedback on several different responses, see <feedback> tied to an <award> in the reference.

Require the exact form

By default (x+1)^2 is accepted as the answer to “expand (x+1)^2,” because it is equivalent. To force the reader to actually do the work, add symbolicEquality, which compares the written form rather than the value.

On its own, symbolicEquality is strict about order too: 1 + 2x + x^2 would be marked wrong. Add simplifyOnCompare to permit reordering and basic simplification while still requiring an expanded answer.

Even now the factored form (x+1)^2 is rejected, because simplifyOnCompare does not expand. If you also want to accept the factored form, add expandOnCompare.

simplifyOnCompare has several levels — from no simplification, through simplifying only numbers or only reordering terms, up to full simplification — that let you tune exactly how much rearranging counts as the same answer. The simplifyOnCompare reference example spells out each option and shows its effect.

Allow for rounding

When the answer is a decimal approximation, use allowedErrorInNumbers to accept responses within a tolerance.

By default the tolerance is a fraction of the correct value (so allowedErrorInNumbers="0.01" means 1%). Adding allowedErrorIsAbsolute makes it an absolute amount instead — here, anything within 0.01 of 1.41 is accepted.

Ask for a list of values

Write several values separated by commas and Doenet treats the answer as a list. Add unorderedCompare so the order doesn’t matter, and matchPartial to award credit for getting some of them.

A reader who enters -5, 2 earns full credit; one who enters just 2 earns half.

Let Doenet compute the answer key

The correct answer doesn’t have to be a value you type — it can be a component that computes it. Here the answer key is whatever the <derivative> evaluates to.

The reader is graded against 3x^2 without your ever writing it — change f and the answer key updates itself. (As always, equivalent forms like 3 x^2 or 3*x^2 are accepted.) The same idea works with any computed math: a <math> built from named values, or a randomly generated quantity.

Where to go next

• Advanced Mathematical Questions — the <award> + <when> construction: accepting any value that fits a condition, combining several inputs, checking factored form, comparing intervals and sets, and a varying number of blanks.
• <answer> reference — the full list of <answer> attributes and properties.
• <mathInput> reference — for explicit control over the input box.
• <feedback> reference — more ways to show messages in response to an answer.
• Writing Accessible Activities — more on labeling inputs so every reader can use your questions.