Notes

A prose-first, semantically grounded notebook that happens to be a website.

These notes are written with two audiences in mind: my future self, and a competent stranger who arrives without context. The structure exists to support explanation, not to replace it.

Tools

`just` Task Runner

just is a command runner that values explicitness over cleverness. It makes the operational shape of a project legible at a glance, which matters more to me than historical compatibility or maximal flexibility.

The project lives at github.com/casey/just, and its README is unusually worth reading in full.

What just calls a recipe is simply a named intention. A recipe may depend on other recipes, and those dependencies are declared directly, rather than being inferred from filenames or timestamps.

Recipe: A named task consisting of one or more shell commands, intended to be read by humans first.
Dependency: Another recipe that must complete before this one runs.
Parameter: A value supplied at invocation time, shaping the behavior of a recipe without modifying it.

In practice, this leads to small entry-point recipes that compose others. The file reads more like a table of contents than a build script.


dev:
    just build
    just test

A minimal development entry point composed from smaller recipes.

Writing Style and Structure

These notes are influenced by a simple idea often associated with Feynman-style explanation: if you cannot explain something clearly in ordinary language, you do not yet understand it.

Structure is allowed to emerge from explanation, not the other way around. Paragraphs come first. Headings are added only when the reader needs help re-orienting.

A useful test is this: if all headings were removed, the text should still read sensibly from top to bottom.

Paragraphs: Each paragraph should express a single idea. If a paragraph contains more than one conceptual move, split it.
Headings: Headings orient the reader; they do not carry explanation. If a heading needs a comma or a justification clause, it probably belongs in the prose.
Examples: Examples are tests of understanding. If an example does not clarify the idea, remove it or replace it.

Feynman-Style Checklist

Could I explain this to a smart stranger without jargon?
Is each paragraph doing one conceptual job?
Do examples test the claim, rather than decorate it?
Are headings orienting, not explaining?

Heading Capitalization

Headings are capitalized using a restrained, human form of title case. They are treated as names, not sentences.

h1: The name of the document or knowledge object.
h2: Domain or category names. Short, noun-heavy, stable over time.
h3: Concept or object names. Labels, not explanations.

If a heading starts to read like a sentence, move the explanation into a paragraph below it.

Semantics and Attributes

Plain HTML already carries a great deal of meaning. Attributes should be added only when they clarify intent for either humans or machines.

Two attribute families are occasionally useful here: data-* and ARIA.

data-*

Custom attributes for attaching non-visual meaning to elements. Useful when you want to mark “what kind of thing this is” without changing structure.

When to Use data-*

Use them when you have code that will read them, or when you notice repetition that could be made explicit (for example, distinguishing a “tool note” from a “concept note”).

When Not to Use data-*

Do not add them speculatively. If nothing consumes the data yet, it is probably too early.

ARIA Attributes

Accessibility hints for assistive technologies. Prefer native HTML semantics first; add ARIA only where meaning would otherwise be unclear.

Useful ARIA Patterns Here

aria-label on nav to state the kind of neighborhood (“Related Concepts”, “Further Reading”, etc.).
aria-label on dl to describe the role of the definitions (“Key Terms”, “Patch Notes”, etc.).

ARIA to Avoid

Avoid roles that duplicate what the element already expresses (for example, adding role="navigation" to <nav>).

A guiding rule: if the meaning is already clear from the element and its content, no attribute is needed.

Closing Note

These notes are not optimized for search engines, frameworks, or static analysis. They are optimized for sustained thinking over time.

If structure begins to feel heavy, return to sentences and explanation first.