didactic-notes

What this skill does

# Didactic Notes: Literate Pedagogy

This skill documents pedagogical design decisions in educational materials, analogous to how literate programming documents code design decisions.

## Reference Files

This skill includes detailed references in `references/`:

| File | Content | Search patterns |
|------|---------|-----------------|
| `latex-examples.md` | Restatable LOs, citations, complete examples | `restatable`, `\cref{}`, `biblatex` |
| `beamer-patterns.md` | Mode splits, overlays, verbose environments | `\mode<article>`, `uncoverenv`, `\textbytext` |
| `semantic-environments.md` | Environment selection, generalizations | `definition`, `remark`, `example`, `block` |

## Core Principle

**Document not just what you teach, but *why* you teach it that way.**

Just as literate programming makes code reasoning explicit, didactic notes make pedagogical reasoning explicit using `\ltnote{...}` from the LaTeX `didactic` package.

## Quick Example

**Without didactic notes:**
```latex
\begin{activity}\label{PredictOutput}
  What do you think this function returns?
\end{activity}
```

**With didactic notes:**
```latex
\begin{activity}\label{PredictOutput}
  What do you think this function returns?
\end{activity}

\ltnote{%
  Following try-first pedagogy, we ask students to predict before
  explaining. This creates contrast between their mental model and
  the actual behavior, helping them discern the critical aspect.
}
```

### Anti-pattern: visible variation labels

Pedagogical labels such as \enquote{What varies} and \enquote{What stays
invariant} belong in notes, not in the student-facing body text.

**Bad:**
```latex
These two examples form a deliberate contrast.

\begin{description}
\item[What varies] Whether [[base_url]] is passed explicitly.
\item[What stays invariant] The helper, the question, and the layout.
\end{description}
```

**Good:**
```latex
\ltnote{%
  \textbf{Variation pattern}: Contrast
  \textbf{What varies}: Whether [[base_url]] is passed explicitly.
  \textbf{What stays invariant}: The helper, the question, and the layout.
}
```

## The `didactic` Package

### Package Setup

```latex
\usepackage[marginparmargin=outer]{didactic}
```

Options:
- `marginparmargin=outer` - Place margin notes on outer margins
- `inner=20mm`, `outer=60mm` - Set margin widths
- `notheorems` - Disable automatic theorem environments

### The `\ltnote` Command

Creates margin notes documenting pedagogical rationale:

```latex
\ltnote{%
  We want to investigate what people think literate programming is.
  This will help us understand the correctness of their prior knowledge.
}
```

## Learning Objectives with Restatable

Use `restatable` environment for learning objectives that can be referenced throughout:

```latex
\begin{restatable}{lo}{FilesLOPersistence}\label{FilesLOPersistence}%
  Förklara skillnaden mellan primärminne och sekundärminne.
\end{restatable}
```

**Key points:**
- Use **mnemonic labels** (e.g., `FilesLOPersistence`, not `FilesLO1`)
- Add `\label{MnemonicLabel}` for `\cref{}` support
- The `%` after opening brace prevents unwanted whitespace

### Referencing LOs

**Method 1: `\cref{}`** (Recommended for detailed notes):
```latex
\ltnote{%
  Relevanta lärandemål:
  \cref{FilesLOPersistence}

  \textbf{Kritiska aspekter för} \cref{FilesLOPersistence}:
  \begin{itemize}
    \item \textbf{Persistens}: Data överlever avstängning
  \end{itemize}
}
```

**Method 2: Starred commands** (Compact):
```latex
\ltnote{%
  Relevanta lärandemål:
  \FilesLOPersistence*

  \textbf{Kontrast}: Typ av minne (primär vs sekundär).
}
```

**CRITICAL**: LO commands cannot be inside `\begin{itemize}` or other list environments.

## When to Use `\ltnote`

Document:

1. **Learning objectives addressed**: Reference with `\cref{}` or starred commands
2. **Pedagogical strategies**: "We use try-first pedagogy to activate prior knowledge"
3. **Variation theory patterns**: Contrast, generalization, fusion
4. **Critical aspects students should discern**
5. **Design trade-offs and decisions**
6. **Assessment purposes**: "This question gauges prior knowledge"
7. **Mentipy question intent**: What a live poll, QR question, or open-text prompt should reveal
8. **Future improvements**: Notes for refining material

When using Mentipy in slides or handouts, document why that question appears
at that moment, what responses are expected to reveal, and how the result will
shape the explanation or discussion that follows.

## Writing Effective Notes

### CRITICAL: Connect to Learning Objectives

Variation patterns must be tied to specific learning objectives:

```latex
\ltnote{%
  Relevanta lärandemål:
  \cref{FilesLOPersistence}

  \textbf{Variationsmönster}: Kontrast

  \textbf{Vad som varierar}: Typ av minne (primär vs sekundär)
  \textbf{Vad som hålls invariant}: Behovet att lagra data

  \textbf{Kritiska aspekter för} \cref{FilesLOPersistence}:
  \begin{itemize}
    \item \textbf{Persistens}: Studenten måste urskilja att filer
      löser problemet med datapersistens.
  \end{itemize}
}
```

### Structure Your Notes

1. **State learning objectives**: What should students learn?
2. **Reference theory**: Connect to established learning principles
3. **Explain the mechanism**: How does this design support objectives?
4. **Note alternatives**: What else could work?

### Language Consistency

**CRITICAL**: Match the language of `\ltnote` content to the surrounding document.

```latex
% Good - Swedish document with Swedish notes
\ltnote{%
  \textbf{Variationsmönster}: Kontrast
  Vi varierar operationen medan vi håller mönstret invariant.
}

% Use \foreignlanguage for English terms without translation
\ltnote{%
  Vi använder \foreignlanguage{english}{try-first pedagogy} här...
}
```

### Choosing Between Detailed and Compact Notes

**Use detailed notes with `\cref{}`** when:
- Writing comprehensive annotations
- Explaining multiple critical aspects
- Need prose-style integration

**Use compact notes with starred commands** when:
- Space is limited
- Quick overview needed
- Simple annotations suffice

## Citing Pedagogical Research

Use biblatex commands instead of hardcoded references:

```latex
\ltnote{%
  Following \textcite{MartonPang2006}, we vary the operation...
}
```

Common commands:
- `\textcite{key}` → "Marton and Pang (2006)"
- `\parencite{key}` → "(Marton and Pang 2006)"

**Best practice**: Use separate `ltnotes.bib` for pedagogical references.

## Integration with Learning Theories

### Variation Theory

Document how material creates patterns of variation:

```latex
\ltnote{%
  \textbf{Mönster}: Generalisering
  \textbf{Varierar}: Programmeringsspråk (Python vs Java)
  \textbf{Invariant}: Algoritmisk princip
}
```

### Try-First Pedagogy

Explain when and why you ask students to attempt before explaining:

```latex
\ltnote{%
  Following try-first pedagogy, we ask students to predict the output
  before running the code. This creates a knowledge gap that makes the
  subsequent explanation more meaningful.
}
```

### Cognitive Load Theory

Note considerations about cognitive load:

```latex
\ltnote{%
  We introduce only two parameters here to manage cognitive load.
  Additional parameters will be introduced after students master the
  basic pattern.
}
```

## Semantic Environments

See `references/semantic-environments.md` for details.

Key environments: `activity`, `exercise`, `question`, `remark`, `definition`, `example`, `block`

### Generalizations After Examples

Capture generalizations in semantic environments AFTER examples:

```latex
\begin{example}[Läsa fil]
  with open("data.txt", "r") as fil:
      innehåll = fil.read()
\end{example}

\begin{example}[Skriva fil]
  with open("data.txt", "w") as fil:
      fil.write(text)
\end{example}

\begin{remark}[Filhanteringsmönster]
  All filhantering följer: öppna → bearbeta → stäng.
\end{remark}
```

## Beamer Patterns

See `references/beamer-patterns.md` for details.

### Key Points

- Notes are hidden by default in slide