Skip to main content
ScaleMath

Explain before you teach

Explanation is not only what comes after a tutorial. A reader who lacks the model of a system will not get through the tutorial at all.

Primary user need: I want to understand.

Explanation provides context, background, relationships, reasons and trade-offs. The subject determines the scope rather than a particular task. It may cover why a product behaves in a particular way, how concepts relate, design or technical decisions, trade-offs between approaches, background knowledge, or alternative ways of thinking about a problem.

It should not become the primary home for step-by-step instructions or detailed lookup information. Short illustrative procedures are fine where they help explain the subject. If users are likely to follow those steps specifically to accomplish a task, write or link a how-to guide instead.

Orientation belongs at the front

Explanation is routinely filed as something a reader reaches once they have already learned the basics. That is the wrong way round for a complex product, which needs its shape explained before any tutorial will land.

We handle that deliberately. An orientation page that gives the reader the model of a system, what its main objects are and how they relate, is explanation, and it is often the correct first page in a section rather than the last. Where a tutorial assumes a mental model the reader does not have, the fix is usually an orientation page in front of it, not a longer tutorial.

The failure we see most often is the opposite: explanation scattered through task-focused pages until neither the instructions nor the concepts work on their own.

Need this applied to your documentation?

We audit, restructure and write product documentation for B2B software companies.

Product documentation servicesRun a free documentation audit
ScaleMath
  • Full stack, senior team: you get us, not just one person that's good at one thing.
  • Your strategic partner: we're here to serve you. Get our input on strategy, product, customer experience, UX, and more.
  • We've helped renowned companies like:
AtarimAAWPWP Fusion