Writing Explanations

Make lesson prose clearer, more direct, and easier for students to follow

Explanations in Internote should feel guided. The student is not just reading information; they are being moved from what they already know toward a new idea.

Lead with the Point

Start a scene by saying what the scene is about. Avoid making students infer the point from several paragraphs of setup.

Lead Clearly

Instead of: "There are many ways functions can change as x gets larger."

Try: "A positive gradient means the function is increasing at that point."

Define Before You Use

When a term is new, define it before using it in an explanation or exercise.

definition{
    A coefficient is the number multiplying a variable.
}(term: Coefficient)

In $3x^2$, the coefficient is $3$.

definition{
    A coefficient is the number multiplying a variable.
}(term: Coefficient)

In $3x^2$, the coefficient is $3$.

Chalk

Read-only

Short definitions are better than complete definitions when the goal is first understanding. Add precision later once the student has a foothold.

Use Examples as Bridges

An example should connect the abstract idea to a concrete case.

State the example
Name the step you are taking
Show the result
Explain why that step was valid

example{
    To simplify $2x + 3x$, combine like terms.

    Both terms contain $x$, so we add the coefficients:

    $2x + 3x = 5x$
}(title: Combining Like Terms)

example{
    To simplify $2x + 3x$, combine like terms.

    Both terms contain $x$, so we add the coefficients:

    $2x + 3x = 5x$
}(title: Combining Like Terms)

Chalk

Read-only

Keep Scene Text Short

Long scenes make students scroll, skim, or lose the thread. When a scene grows too large, split it by purpose.

One scene for the definition
One scene for the worked example
One scene for practice
One scene for reflection or summary

Write Prompts That Tell Students What to Do

Interactive elements work best when the prompt names the expected action.

Weak: Think about the graph
Strong: Drag the correct word into each blank
Strong: Find the derivative, then enter your answer in simplified form
Strong: Explain why the second answer is not equivalent

If a student could ask "What am I meant to do here?", the prompt needs one more sentence.

Explanation Checklist

The first sentence tells students what the scene is about
New terms are defined before they are used
Examples show both the step and the reason for the step
Exercises ask for one clear action
The scene is short enough to read without losing the main idea

On this page

Lead with the Point Define Before You Use Use Examples as Bridges Keep Scene Text Short Write Prompts That Tell Students What to Do Explanation Checklist

Writing Explanations

Make lesson prose clearer, more direct, and easier for students to follow

Explanations in Internote should feel guided. The student is not just reading information; they are being moved from what they already know toward a new idea.

Lead with the Point

Start a scene by saying what the scene is about. Avoid making students infer the point from several paragraphs of setup.

Lead Clearly

Instead of: "There are many ways functions can change as x gets larger."

Try: "A positive gradient means the function is increasing at that point."

Define Before You Use

When a term is new, define it before using it in an explanation or exercise.

definition{
    A coefficient is the number multiplying a variable.
}(term: Coefficient)

In $3x^2$, the coefficient is $3$.

definition{
    A coefficient is the number multiplying a variable.
}(term: Coefficient)

In $3x^2$, the coefficient is $3$.

Chalk

Read-only

Short definitions are better than complete definitions when the goal is first understanding. Add precision later once the student has a foothold.

Use Examples as Bridges

An example should connect the abstract idea to a concrete case.

State the example
Name the step you are taking
Show the result
Explain why that step was valid

example{
    To simplify $2x + 3x$, combine like terms.

    Both terms contain $x$, so we add the coefficients:

    $2x + 3x = 5x$
}(title: Combining Like Terms)

example{
    To simplify $2x + 3x$, combine like terms.

    Both terms contain $x$, so we add the coefficients:

    $2x + 3x = 5x$
}(title: Combining Like Terms)

Chalk

Read-only

Keep Scene Text Short

Long scenes make students scroll, skim, or lose the thread. When a scene grows too large, split it by purpose.

One scene for the definition
One scene for the worked example
One scene for practice
One scene for reflection or summary

Write Prompts That Tell Students What to Do

Interactive elements work best when the prompt names the expected action.

Weak: Think about the graph
Strong: Drag the correct word into each blank
Strong: Find the derivative, then enter your answer in simplified form
Strong: Explain why the second answer is not equivalent

If a student could ask "What am I meant to do here?", the prompt needs one more sentence.

Explanation Checklist

The first sentence tells students what the scene is about
New terms are defined before they are used
Examples show both the step and the reason for the step
Exercises ask for one clear action
The scene is short enough to read without losing the main idea