Picture a learner who’s just watched their chatbot answer a question for the first time.
The answer is sitting on the screen, the thing they built is clearly working, and the natural next step is to ask it something harder and see whether it holds up.
Instead, the project stops them for several paragraphs on how the chatbot came up with that answer. Everything in those explanations is accurate and relevant, but by the time the learner has read them and reached the next step, the urge to test their chatbot has passed, and they are back to working through instructions.
That urge is what we mean by momentum, and it is easy to lose because someone in the middle of building is already juggling a lot: the file they just changed, the answer on the screen and a hunch about what will happen when they try the next thing. Every explanation we put in their way competes with all of that for the same attention, and whether it is worth the interruption comes down to one thing: did the learner already have a question that this explanation answers?
If they did, it slots into what they are already thinking about and they come out the other side understanding more. If they did not, the explanation has much less reason to be there, so the learner skims it, loses track of what they were about to try, and reach the next step with less energy than they had a minute earlier. This is why the timing of our explanations matters as much as how well we explain them. A clear explanation in the wrong place still costs the learner something, and gives them very little back.
Good editing includes deciding what can wait
Timing tends to get lost during editing, because when a project is not working, the instinct is to add. A confusing step gets a longer explanation, a step people keep getting wrong gets another screenshot, and a step that can fail gets a warning above it. Each of those is a sensible fix on its own. The trouble is that each one also asks the learner to stop and read before they can carry on, so after a few rounds of edits the project is more thorough than it was, but slower to get through, and it became that way one reasonable addition at a time.
That is why, when we edit NextWork projects, we try to test for something else alongside accuracy - when will the learner actually need this? The answer to that question determines where the explanation goes:
If the learner cannot complete the next action without it, it belongs directly before that action, because that is the one place they are guaranteed to read it.
If it explains something they have just done, it belongs after, because an explanation makes far more sense when you have the result in front of you.
If only some learners will want it, it should be there for them and easy for everyone else to skip.
And some material, once you ask when it is needed, turns out to have no good moment in this project, which usually means it belongs in a different one. Take the chatbot example again. the explanation of how it came up with its answer is far more interesting after the learner has asked it a few harder questions and noticed that some answers were better than others - because at that point, they’d have a reason to want to know.
None of this is an argument for shorter projects or fewer explanations. The learner in the opening still needs to understand how their chatbot came up with its answer, and the project should still tell them.
What changes is simply the timing. Protecting momentum is mostly a matter of asking, of everything we add, whether it arrives in time to change what the learner does next. If it does not, it can wait.
Happy learning,
