Apply variation theory of learning to structure content using contrast, generalization, and fusion patterns. Variation must target the critical aspects of the learning objective. Use proactively when (1) writing educational materials, explanations, tutorials, or lecture slides, (2) designing or reviewing examples in documentation, READMEs, or literate programs (.nw files), especially when multiple examples illustrate alternative approaches to the same task, (3) structuring code examples, CLI usage examples, or API examples where the reader should notice what differs between alternatives, (4) user mentions variation theory, learning theory, pedagogy, contrast, invariance, or critical aspects. Also activate when asked to elaborate, make concrete, or add examples to existing content. Works alongside literate-programming and didactic-notes skills.
This skill applies the variation theory of learning, developed by Ference Marton and colleagues, to structure content for optimal learning.
This skill includes detailed references in references/:
| File | Content | Search patterns |
|---|---|---|
common-violations.md | Generalization-before-example violations | BAD, GOOD, violation types |
latex-examples.md | Side-by-side contrast, semantic environments | \textbytext, \ltnote, Swedish |
The object of learning is what is to be learned. Understanding develops when learners discern the critical aspects of the object of learning.
Marton's central principle: "to learn something, the learner must discern what is to be learned. Discerning the object of learning amounts to discerning its critical aspects."
The necessary condition for discernment: learners must experience variation in a dimension corresponding to that aspect, against the background of invariance in other aspects.
Key insight: "When some aspect of a phenomenon varies while another aspect remains invariant, the varying aspect will be discerned."
FUNDAMENTAL PRINCIPLE: Variation must occur in the critical aspects of the object of learning. Arbitrary variation does not lead to learning.
Before designing any pattern of variation:
The principle "one thing at a time" applies to dimensions (aspects), NOT to values within a dimension.
r, w, a)The principle:
Research evidence: Teaching punctuation marks separately: 15% improvement. Teaching all three together with contrast: 63% improvement.
Anti-pattern: Creating variation in aspects irrelevant to the learning objective.
Example: Teaching "why files need open/close":
Variation theory is not limited to classroom teaching — it applies whenever a reader must discern differences between alternatives. Documentation, READMEs, and literate programs routinely show multiple ways to achieve the same goal. The contrast pattern ensures the reader's attention falls on the method (the critical aspect) rather than on incidental details.
When showing alternative approaches to the same task, use the same concrete names, filenames, and identifiers across all examples. If the names change between examples, the reader must determine whether the name change is meaningful — this distracts from the actual difference (the method).
A tool offers two ways to share a log: push/clone via Git, or export/play via a bundle file. The object of learning is "how to share a log"; the critical aspect is "which delivery method to use."
BAD — names vary alongside the method, obscuring what actually