Write Step Text That Keeps Learners Focused
A Learner reads step text in the moment they have to act, so every extra word competes with the task. This article is for Skyllful Studio Users who build Lessons and shows how to write step text a Learner can act on at a glance, how one step description becomes the Talkthrough narration, the Walkthrough prompt, and the Practice hint, and what to leave out.
Why does step text matter so much?
Step text is read at the exact moment the Learner has to act. Their attention is already split between the words and the screen, and every extra word pulls some of it away from the task. Clear step text lets the Learner read, act, and move on. Unclear step text makes them stop and work out what you meant.
It also matters because you write it once and the Learner meets it three times. The description on a step's General tab becomes the Talkthrough narration, the Walkthrough prompt, and the Practice hint. A clear description gives all three modes a strong start. An unclear one weakens all three.
What does clear step text look like?
Rule |
Instead of |
Write |
|---|---|---|
| Lead with the action | The next thing you will want to do is tap Returns. | Tap Returns. |
| Name the control exactly as it reads on screen | Tap the button to save. | Tap Save Order. |
| Say where it is when the Learner might have to search | Tap Save Order. | Tap Save Order at the bottom of the form. |
| Give the value to enter | Enter the quantity. | Enter 12 in Quantity. |
| Use the words the job uses | Enter the stock keeping unit identifier. | Enter the SKU. |
| Add a reason only when it changes what the Learner does | Tap Submit. This is an important step. | Check the invoice number before you tap Submit. A credit on the wrong invoice holds the customer's next order. |
| Keep to one control per step | Tap Submit, then tap View Total. | Tap Submit. Put "Tap View Total" in the next step. |
Note: A step holds one control, plus any text entries on the same screen. Step text can ask the Learner to fill in several fields and then tap the one control. Step text that asks for a second control is describing a step that does not exist yet.
How does one description become three?
Each mode takes its own copy of the step description from the General tab. You can then reword each copy to suit how the Learner meets it in that mode.
Mode |
Where the description goes |
How to reword it |
|---|---|---|
| Talkthrough | The narration and captions, called the VO Script | The Learner is watching, not acting. Describe what is happening and why it matters: "The order is saved, and the customer's credit is applied." |
| Walkthrough | The prompt the Learner reads on screen | Usually no change. The General tab description is already written as an instruction. |
| Practice | The hint the Learner sees after a wrong action | The Learner has already tried. Point them where to look rather than repeating the full instruction: "Look at the bottom of the form." |
Note: Editing a mode's copy changes only that mode. It never changes the General tab description or the other modes, so you can reword Talkthrough narration without affecting what Walkthrough shows.
What should stay out of step text?
Anything the Learner does not need to perform this step. Each of these competes with the task:
- Background and policy. The reason a process exists belongs in the opening of the Lesson, not in the middle of a step.
- Describing the screen. The Learner can see it. The Replica looks exactly like the application they use on the job, so the words only need to point to what to do.
- Filler and encouragement. "Great job, now let's move on" costs the Learner time on every step and tells them nothing.
- Instructions for a later step. They are forgotten by the time the Learner gets there, and they are repeated when they arrive.
Common questions
How long should step text be? One short sentence for most steps. Two when the Learner needs a reason or a value. If a step needs more, it is usually two steps or it holds background that belongs elsewhere.
Should Talkthrough narration read the same as the Walkthrough prompt? No. Narration is heard while the Learner watches, so an instruction like "Tap Save Order" sounds odd when the Learner is only watching. Reword it to describe the action as it happens.
What if a word is mispronounced in the narration? Talkthrough lets you set how a word should sound without changing the text Learners read. Set Up Talkthrough Mode shows how.
Do I need to write the why in every step? No. Write the why once at the start of the Lesson. Add a reason to a step only when it changes what the Learner does at that step, such as a check they must make first.
Where does this idea come from? John Sweller's research on mental load found that every piece of information a Learner has to process competes for the same limited attention, so anything not needed for the task makes the task harder. Richard Mayer's research on multimedia learning found that words work best when they point the Learner to what is on the screen instead of repeating it.
Skyllful Knowledge Base | Content Creators