Documentation at different levels should target users of different proficiency

What it is

Since a system model naturally splits into functional, structural, and implementation layers, and different users need to operate at different layers, documentation shouldn't be a single piece written for an "average user." It should be organized by layer instead: novices reach only functional-level explanations, users planning complex tasks can find structural-level explanations, and users who need to go deeper (developers, power users) can find implementation-level explanations — none of them forced to read a layer they don't need.

Why it happens

A single document, in trying to "serve everyone," ends up mixing all three layers into the same passage: a novice reading a functional explanation runs into implementation-level jargon partway through and has to stop to make sense of something irrelevant to them; an advanced user looking for structural or implementation detail has to dig through a mass of introductory functional-level material to find it. Each group's needs drag down the other's reading efficiency. Organizing documentation by layer aligns the granularity of the content with whatever layer the reader is currently operating at: readers only need incremental learning built on top of the layer they already have, instead of starting over from the functional level every time.

Where it stops holding

• This principle requires being able to tell accurately which layer a given user is currently operating at. If a product's user base has very little variation in layer (a highly homogeneous professional tool used exclusively by one role), layered documentation offers limited benefit, and the cost of maintaining multiple documents can exceed it.
• Layer isn't fixed once and for all: the same user may only need functional-level documentation early in their use of a product, then actively seek out structural or even implementation-level content as their proficiency grows. Documentation structure needs to support this kind of progressive lookup rather than assuming a user stays forever at whatever layer they were assigned as a beginner.

Applying it

• Set up separate entry points in the documentation's information architecture for the functional level (what it can do, for beginners), the structural level (how to combine functions for complex tasks, for advancing users), and the implementation level (internal mechanisms, for experts/developers), allowing cross-links between them without forcing readers to pass through all three in sequence.
• End each functional-level document with a "want to learn more" link pointing to the corresponding structural-level document for that task, rather than cramming structural information into the body of the functional explanation and adding to a beginner's reading load.
• How to check: sample traffic sources and bounce behavior across documentation pages at different layers. If novices frequently jump from a functional-level document to an implementation-level page and quickly bounce back, that functional-level document has likely mixed in unnecessary implementation-level information, pushing users out of the layer they should have stayed at.

Related

• Same group: A7.15.1 The functional level describes what a system can do, mapped directly to user goals · A7.15.2 The structural level describes how functions are organized and related, the basis for navigating complex tasks · A7.15.3 The implementation level describes concrete underlying mechanisms, which most users don't need and shouldn't be required to understand · A7.15.4 An interface that exposes implementation detail while omitting the structural level leaves users knowing the parts but unable to assemble the whole
• Nearby: A7.10 Explicit expression of the conceptual model
• Search terms: layered documentation · progressive disclosure · system model levels · user proficiency