A Working Model for Durable Technical Notes

This is demonstration content, written to exercise the long-form article layout. It should be replaced by Ryan’s own account once real source material is available.

The problem is not capturing information#

It is easy to save a link, copy a definition, or preserve a code sample. The harder question is whether the note still explains why it mattered six months later.

I can model the useful part of a technical note as three pieces:

$$\text{durable note} = \text{question} + \text{model change} + \text{evidence}$$

The equation is deliberately informal. Its purpose is to keep a note anchored to a real change in understanding, instead of letting it become a compressed textbook chapter.

Start with the contradiction#

A strong note often begins where an earlier mental model stopped working. Consider a generic parsing function:

type Token = { kind: string; value: string };

export function parse(tokens: Token[]) {
  if (tokens.length === 0) return null;
  return buildSyntaxTree(tokens);
}

The code itself is not the durable insight. A useful note records what assumption was challenged: perhaps “valid tokens imply valid syntax” turned out to be false. The code then becomes evidence for the boundary between tokenization and parsing.

Separate observation from explanation#

I find it useful to distinguish the things a note can claim:

Layer	Question	Typical evidence
Observation	What happened?	Output, trace, measurement
Explanation	Why might it happen?	Model, source, derivation
Decision	What will change?	Constraint, trade-off, test

This prevents a successful experiment from silently becoming a universal claim. It also leaves room for uncertainty.

A note can be useful before it is complete, but it should be honest about which parts are observed and which are inferred.

Keep examples small enough to inspect#

For a sequence of length $n$, a full attention matrix contains $n^2$ pairwise scores. Doubling the sequence length therefore produces four times as many scores:

$$A = \operatorname{softmax}\left(\frac{QK^\top}{\sqrt{d_k}}\right), \qquad A \in \mathbb{R}^{n \times n}$$

That statement is easier to trust when the dimensions are visible. Good examples expose the shape of the reasoning, not merely the final answer.

A lightweight editing pass#

Before publishing, this checklist catches most weaknesses:

1. Can I state the original question in one sentence?
2. Is my earlier assumption visible without being dramatized?
3. Does every technical claim have enough support?
4. Did I separate my own reasoning from added background?
5. Are the unresolved questions still present?

The goal is not to make every note comprehensive. The goal is to make its boundaries legible.¹

What remains open#

This model does not decide when a note should become an article. That boundary is likely editorial: an article earns its length by connecting several ideas into one argument, while a note can remain focused on a single question.

Footnotes#

1. This footnote exists to validate footnote rendering and keyboard-reachable backlinks. ↩