When we write a NextWork project, we spend a surprising amount of time deciding how much to explain. Leave out too much and a learner gets stuck wondering which window to open, where to save a file, which version to install. Explain every choice and supply every answer, and a learner can finish the project without having much opportunity to think for themselves.
“Assume intelligence, not prior knowledge” is how we think about that tension. We want learners to tackle work they have never done before, using the tools professionals use. That requires us to explain unfamiliar steps carefully while still asking learners to make choices, test ideas and understand their results.
Why we don’t assume prior knowledge
Experience is uneven. Someone can be comfortable writing code and be completely new to using a local LLM. A person changing careers can bring years of problem-solving experience to a tool they have never opened. Needing detailed instructions in one part of a project tells us little about what they can handle in another.
As project writers, we have to account for that unevenness throughout the project. For example, “clone the repository” may seem straightforward until you consider whether the learner:
has Git installed,
knows what a “repository” is,
can find the repository in GitHub
knows how to open their terminal,
is authenticated to GitHub in the terminal,
can run the command for cloning,
has somewhere to store their cloned repository, and
can verify whether the cloning was successful.
To make sure we’re not assuming prior knowledge, we need to test our own instructions from scratch - ideally with no tools installed or accounts created - to catch steps a learner could struggle to follow. We also want to provide explanations in more ways than one:
use screenshots to visually show which setting to change
separate Windows and Mac instructions into tabs, to prevent someone from following steps that do not apply to their OS
use callouts to explain technical terms we’re introducing in the middle of a step, so learners become familiar with the jargon without breaking out of flow.
Adding all of this takes care and craft. Every explanation asks for the learner’s attention, and repeating information they already have can make a straightforward task feel laborious. The aim is to give them just enough information to follow an instruction and understand its purpose, without making them read a lesson on every single topic.
Why we assume intelligence
Needing an explanation does not mean needing someone else to make the decision. A learner who has never seen a setting may still be able to choose its value once they understand what it changes. If we automatically choose for them, we remove an opportunity to practise that judgment.
This matters because finishing a project is only part of the goal. We want learners to be able to choose tools, assess their results and investigate problems when they build independently. A project that prescribes every action gives them little practice doing that, however smoothly it runs.
Our stance is to improve the explanation before lowering the expectation. We intentionally lead learners down a path where they encounter an error, then show them where to find an error message and how to test a possible cause without immediately supplying the fix. That asks them to reason from information they have, rather than guess at information we left out.
This is the standard behind “assume intelligence, not prior knowledge.” It does not mean explaining everything, but it also does not mean leaving beginners to infer instructions that assume they’ve done it before. It means being precise about which difficulty belongs to the skill they’re building, and which difficulty exists only because this is the learner first time in this environment.
When this is done well, learners get to the finish line of the project with tools they know how to use, decisions they can explain, and practise with solving problems - all skills that make them capable of building on their own.
Happy writing,
