+++
title = "HtWaH: Typesetting"
author = "Mark"
backlinks = true
+++

## Table of Contents

This page is part of my [how to write a handout](/htwah) series.

- [Part 1: Typesetting](.) **{{color(--green, "<-- you are here")}}**
- Part 2: Notation
- Part 3: Designing lessons
- Part 4: Designing puzzles
- Part 5: Leading a class
- Part 6: Resources

<hr style="margin-top: 5rem; margin-bottom: 5rem"/>

## The Medium

### Always teach in print

A physical handout is three-dimensional. Every point inside it has a horizontal, vertical, and azimuthal position. This makes it easy to navigate, and thus easier to understand.

Navigation is inseparable from memory---this fact has been known for millennia.[^1]
Lessons presented on a screen do not take advantage of this; lessons presented on paper do.

### Never print on both sides

Double-sided handouts break this spacial intuition. The act of turning a page upside-down severs its connection to physical space. Do not entangle your students in the pages of a double-sided worksheet---print only on one side.

{{color(--grey, "This is not true of books, which are presented in a fundamentally different way.")}}

Double-sided handouts also clutter the page with the opposite side's nodes. Even when using a pencil, work on the front of a page makes its way to the back.

<br/>

> Humans live and learn in the real world. \
> Paper is a renewable resource. \
> Edu-tech is bullshit.

[^1]: See: method of loci

<hr style="margin-top: 5rem; margin-bottom: 5rem"/>

## Spacing

Writing is visual. It catches the eye before it has a chance to catch the brain.[^2] A good lesson takes advantage of this: it uses space to frame its content.

Take care to organize the text you produce. Provide a clear visual boundary between separate ideas---unbroken waterfalls mathematical text are difficult to parse---and be sure to place visual boundaries only where there are logical ones.

Use empty space generously, but never use it wastefully. Too much space is just as distracting as too little.

### Leave space for work

If you force your students to cram their work into the margin,
their understanding will have a similar quality. \
Give them space to work and space to think.

{{color(--grey, "This rule only applies to handouts. Lecture notes and textbooks do not need to worry about this, since students should work through them on a separate sheet of paper")}}

Every problem should be followed by a `\vfill`. \
There are exceptions, but they are rare.

If your handouts include solutions
{{color(--grey, "(they should)")}}
observe the following rule: each problem's typeset
solution should fit in the empty space after the problem.
This isn't perfectly accurate estimate of space
(your students will likely need more), but it is a very good minimum.

{{color(--grey, "If your students will be drawing pictures, make each gap twice as bit as it needs to be.")}}

In a handout that is typeset well, the layout of each page should not
change when solutions are shown. This helps you give students enough
room to solve each problem, and keeps page numbers consistent between
instructors' and students' handouts:

<div style="display: flex; flex-direction: row; gap: 1rem; height: 50rem">
	<embed type="application/pdf" src="/assets/htwah/sols-a.pdf" width="100%" height="100%" />
	<embed type="application/pdf" src="/assets/htwah/sols-b.pdf" width="100%" height="100%" />
</div>

<br>

### Break with intention

A page should _never_ break in the middle of a definition, problem, or theorem.

A page should _never_ break between the first mention of a concept and the problems used to introduce it.

New sections should _always_ start on a new page.

{{color(--grey, "Unlike the previous comments on spacing, the above rules apply to all formats. Whether you are writing a textbook, a handout, or lecture notes, do not allow your page breaks to break as student's train of thought.")}}

These rules are easy to follow if you leave space for work: \
Place your `\pagebreak`s well and let `\vfill` handle the rest.

### Separation

Problems, definitions, and theorems should come in clear blocks.
It should be easy to tell which element of a page each line of text
relates to[^3].

The [Open Logic Project](https://openlogicproject.org/) provides a
striking example of this. Definitions are boxed and titled---it is abundandly
clear that these are the definitions we will be using in the future.

It is also a good idea to mark the first use of a term. \
In the example below, this is done with italicized text.


<div style="display: flex; flex-direction: row; gap: 1rem; height: 50rem">
	<embed type="application/pdf" src="/assets/htwah/definitions.pdf" width="100%" height="100%" />
</div>

Of course, not all texts need such aggressive grouping. I tend to avoid clear "boxing" in [my lessons](/handouts), opting for subtle grouping by whitespace instead. This is a matter of taste.

{{color(grey, "Regardless of implementation, visual boundaries should match conceptual boundaries. It should be easy to see where each logical element ends.")}}

Finally, remember that too much separation is just as distracting as too little.
Balance is key.

### Proximity

Different elements should be far apart, and related elements should be close together[^4]. This rule is often violated by equations and diagrams.
Consider the two pages below:

<div style="display: flex; flex-direction: row; gap: 1rem; height: 50rem">
	<embed type="application/pdf" src="/assets/htwah/spacing-a.pdf" width="100%" height="100%" />
	<embed type="application/pdf" src="/assets/htwah/spacing-b.pdf" width="100%" height="100%" />
</div>


The circuit diagram on the left is clearly a part of the setup at the top of the page. It is not connected to Problem 14.

Compare this to the equations under Examples 1.25 and 1.26 on the right. These elements do not have a clear owner, since they are just as far from the text above them as the text below.

> The visual layout of a lesson must match its logical layout. \
> Similar items are close, different items are far. \
> Key information should be clearly visible and easy to find.

[^2]: See "Paragraphs" in William Zinsser's _On Writing Well_.
[^3]: See: [the chunking principle](https://lawsofux.com/chunking/)
[^4]: See: [the law of proximity](https://lawsofux.com/law-of-proximity/)

<hr style="margin-top: 5rem; margin-bottom: 5rem"/>

## Numbering

### Pages

Pages should be numbered unless the document only has one page. There are no exceptions to this rule.

Numbering should be simple: use a single counter that is set to 1 on the first page of the document. Every page should have a number, even if that number isn't visible. This includes frontmatter and the table of contents.

Different numbering systems (`i, ii, iii...` for a preface; `A31, A32, A33...` for appendices) have little value and only make navigation more difficult.

{{color(--grey, "Roman numbering of frontmatter in large textbooks is acceptable, but anything more complicated is unnecessary")}}

### Versions

The document itself should also be numbered. In most cases, a `\today` on the front page of the lesson is all you need.

This helps synchronize the handout you _think_ the class has with the handout that the class _really_ has.

Future instructors {{color(--grey, "(and future you)")}} will be thankful.

### Items

Propositions, definitions, and examples should all be numbered with the same counter. Problems should also use this counter, unless they are only listed at the end of each section {{color(--grey, "(as they often are in textbooks).")}}

Do not use different counters for different objects. Theorem 1 should not follow Definition 2. This is the default behavior of LaTeX, and it is a serious mistake.

Such a numbering system makes it difficult for readers to orient themselves. Say a student is solving Problem 6, which references Theorem 2. Where should she look? Is Theorem 2 on the previous page, or is it near the beginning of the lesson? It could even be on the _next_ page!

The only choice she has is to look through the lesson page-by-page until she finds Theorem 2. Finding Theorem 3 will not help---it would tell her where Theorem 2 _isn't_, but it won't tell her where it _is_.

With a single counter, this is not an issue. Readers are aware of their absolute position at every point in the lesson, and can easily find what they need.

[Open Logic](https://openlogicproject.org/) again provides an example of quality typesetting. Notice how the numbering of Propositions, Definitions, and Examples on the page below is consecutive:

<div style="display: flex; flex-direction: row; gap: 1rem; height: 50rem">
	<embed type="application/pdf" src="/assets/htwah/numbering.pdf" width="100%" height="100%" />
</div>

In long textbooks, prefixing numbers with the chapter index (e.g, the `2` in `2.32` above) is wise. In any other case, a single counter should be enough.

<br>

> Good numbering is simple and consistent. \
> Don't tell me to "look for the fourth theorem". \
> Tell me _where it is_.

<hr style="margin-top: 5rem; margin-bottom: 5rem"/>

## Margins

### Always have a title

Any document you produce should be identifiable by its first page.
Always have a title that tells the reader what they're looking at,
who made it, when, and why.

If you're writing a document that is available in multiple variants (for example, a handout with solutions or an exam with multiple versions), the variant should be easily visible in the title. Note the box under the title in the handout on the left.


<div style="display: flex; flex-direction: row; gap: 1rem; height: 50rem">
	<embed type="application/pdf" src="/assets/htwah/sols-a.pdf" width="100%" height="100%" />
	<embed type="application/pdf" src="/assets/htwah/sols-b.pdf" width="100%" height="100%" />
</div>


This lets us detect errors quickly: we only need to look at the first page of a lesson to know if we printed the wrong variant, handed the students solutions, or graded an exam using the wrong answer key.

### Never have a running header

We already have a title, so a running header adds no value. \
Let your students fill the margin.

### Avoid footnotes

Do not put important information in footnotes. \
Find a way to state it directly.

Footnotes are for trivia, historical notes, or extra reading. \
They are for information your lesson could live without.

This reasoning can be applied to parentheticals, hints, and other auxiliary text:
as a general rule, it should be avoided.

Important information deserves a place in the main flow of the document,
and you should structure your prose so that it fits. Don't stick it on
as an afterthought.

<br>

> If you don't need it, take it out. \
> If you do, put it in. \
> Always introduce yourself.
> Never do so twice.
