variation-theory

What this skill does

# Variation Theory of Learning

This skill applies the variation theory of learning, developed by Ference Marton and colleagues, to structure content for optimal learning.

## Reference Files

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 |

## Core Theoretical Principles

### The Object of Learning

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."

### Variation and Invariance

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."

## Critical Aspects as Focus of Variation

**FUNDAMENTAL PRINCIPLE**: Variation must occur in the **critical aspects** of the object of learning. Arbitrary variation does not lead to learning.

### Identifying Critical Aspects First

Before designing any pattern of variation:

1. **Define the object of learning** - What should learners understand/do?
2. **Identify the critical aspects** - Which features must be discerned?
3. **Design variation IN those aspects** - Create patterns varying the critical dimensions

### Dimensions vs Values

The principle "one thing at a time" applies to **dimensions** (aspects), NOT to **values** within a dimension.

- **Dimension (aspect)**: A category/feature type (e.g., "punctuation marks", "file mode")
- **Values/features**: Specific instances (e.g., punctuation marks like period, question mark, exclamation mark; or file modes like `r`, `w`, `a`)

**The principle:**
- **Vary ONE dimension at a time** - to separate aspects from each other
- **Contrast MULTIPLE values together** - within that dimension

**Research evidence**: Teaching punctuation marks separately: 15% improvement. Teaching all three together with contrast: 63% improvement.

### Common Mistake: Varying Non-Critical Aspects

**Anti-pattern**: Creating variation in aspects irrelevant to the learning objective.

**Example**: Teaching "why files need open/close":
- **Wrong**: Vary filename or content (not critical)
- **Right**: Vary what happens when close() is/isn't called (critical aspect is resource management)

## Applying Contrast in Documentation Examples

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.

### Principle: Keep the Problem Invariant, Vary the Method

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).

### Put Variation Analysis in Notes

When the material is student-facing and the document uses didactic notes,
record pedagogical analysis such as \enquote{What varies},
\enquote{What stays invariant}, and \enquote{What this reveals} in
`\ltnote{...}` via the `didactic-notes` skill.  Keep the visible prose
focused on the example itself and the feature the reader should use.

**Bad** --- student-facing pedagogical meta-commentary:

```latex
These two examples form a deliberate contrast.

\begin{description}
\item[What varies] Whether [[show_url]] is set to [[False]].
\item[What stays invariant] The helper, question, and environment.
\end{description}
```

**Good** --- instructor-facing pedagogical annotation:

```latex
\ltnote{%
  \textbf{Variation pattern}: Contrast
  \textbf{What varies}: Whether [[show_url]] is set to [[False]].
  \textbf{What stays invariant}: The helper, question, and environment.
}
```

### Example: CLI Documentation with Two Delivery Methods

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
changed:

```
# Method 1: push to remote
learnlog set-remote [email protected]:dbosk/demo-log.git
learnlog push

# Method 2: export as bundle
learnlog export -o lecture01.bundle
learnlog play lecture01.bundle
```

The reader sees `demo-log` vs `lecture01` and wonders: does the name
matter?  Is a bundle different from a repository?  The irrelevant
variation in the name competes with the relevant variation in the
method.

**GOOD** — the name is invariant, only the method varies:

```
# Method 1: push to remote
learnlog set-remote [email protected]:dbosk/lecture01.git
learnlog push
...
learnlog clone [email protected]:dbosk/lecture01.git
learnlog play

# Method 2: export as bundle
learnlog export -o lecture01.bundle
...
learnlog play lecture01.bundle
```

Now `lecture01` is invariant across both examples.  The only thing
that changes is the delivery mechanism (push/clone vs export/play),
which is exactly the critical aspect the reader should discern.

### When to Apply This

Activate this pattern whenever you encounter:
- Multiple code examples showing alternative approaches
- CLI usage sections with different flags or subcommands
- API examples with different authentication methods
- Configuration examples with different backends
- Any documentation where "you can also do X instead of Y"

**Self-test:** If two examples differ in more ways than the one
dimension you intend to contrast, eliminate the incidental differences.

### Mentipy for Live Variation

Mentipy can operationalize variation patterns in live teaching.  Use a short
sequence of `mc`, `scale`, `open_text`, or `word_cloud` questions to vary one
critical aspect at a time while keeping the object of learning invariant.
This is especially useful for diagnostic contrast before an explanation and
for checking whether students now discern the critical aspect afterward.

## The Three Patterns of Variation

### 1. Contrast

**Purpose**: Help learners recognize that an aspect exists by experiencing what it is versus what it is not.

**How it works**: Present examples that differ in one critical aspect while keeping all other factors constant.

**Example**: To understand "height," show two objects identical in all respects except height.

**Note**: Contrast achieves *separation*—the critical aspect becomes discernible through experiencing variation.

### 2. Generalization

**Purpose**: Help learners recognize that a pattern or principle holds across different contexts.

**How it works**: Present the same critical value in varied appearances. Keep the critical aspect invariant while varying other (non-critical) aspects.

**Example**: Show the same geometric principle applied to triangles, rectangles, circles.

### 3. Fusion

**Purpose**: Enable learners to experience multiple critical aspects simultaneously as an integrated whole.

**How it works**: Vary several critical aspects at once so learners must attend to their simultaneous interrelationships.

**Example**: In understanding circuits, vary resistance and voltage simultaneously.

## Pedagogical Sequence

Research suggests using patterns in this order:

1. **Contrast** - Vary the critical aspect while keepi