Writing Notes That Age Well

Good technical notes are easy to scan, easy to quote, and clear about the context they came from. They do not need to be long, but they do need to be specific.

Prefer Concrete Headings

Headings should describe the point of the section. A reader should be able to skim them and understand the argument without reading every paragraph.

Use Lists Sparingly

Lists are useful for parallel ideas:

• Constraints that shaped a decision.
• Steps in a repeatable process.
• Tradeoffs that should be compared directly.

When a list becomes a pile of unrelated thoughts, turn it back into prose.

Quote With Purpose

Blockquotes work best when they create a pause or preserve wording that matters.

The goal is not to write more. The goal is to make the next decision easier.

Show the Shape of Code

Short code examples should be complete enough to copy, but small enough that the surrounding explanation still does the work.

type Decision = {
	title: string;
	context: string;
	tradeoffs: string[];
};

The best posts leave behind a useful path: what changed, why it changed, and what to inspect next.