Patterns for compressed-for-humans pages¶

A pattern language for the human-readable layer. Each pattern names a recurring writing problem and the resolved form that worked. 11 patterns; 60+ pages applying them.

🌿 budding tended 2026-05-08 convention patterns alexander appleton

flowchart LR
  problem[recurring writing problem] --> name[name it]
  name --> ctx[Context · Problem · Forces · Therefore]
  ctx --> use[apply on 3+ pages]
  use --> ev[promote to pattern]

1. Lead with L0¶

A reader who only reads the first 30 seconds still leaves with the punchline.

Context. Long technical pages on a site whose readers arrive from a link.

Problem. The reader can't tell whether the page is worth their attention until they've spent five minutes.

Forces. Every page wants to "just give context first." But context is only valuable to a reader who has already decided to stay.

Therefore. Open with a one-sentence (or one-mermaid-L0) summary that says the conclusion. Drill into evidence, history, edge cases below.

Where it shows up. README.md opens with the loop diagram before any prose. docs/MERMAID-CONVENTIONS.md formalises the L0/L1/L2 levels. Wikipedia's lead-section convention is the canonical version.

2. One concept, one page¶

Topography over timelines.

Context. A growing repo where the same idea is touched by many sessions.

Problem. Chronological logs (NEXT.md, session notes) are how the swarm remembers, but they're useless as reference. A reader looking for "what is stigmergy" doesn't want a thread of 40 sessions arguing about it.

Forces. The session log is cheap to write and expensive to read. A concept page is the inverse.

Therefore. For every idea that survives more than three mentions, extract a concept-titled page. The chronology stays in the log; the page stays canonical and is rewritten as understanding grows.

Where it shows up. docs/GLOSSARY.md, docs/SWARM-RATE-DISTORTION.md, each investigation under docs/investigations/. Borrowed from Andy Matuschak's evergreen notes.

3. Vocabulary on hover¶

Don't redefine on every page; link a glossary entry that pops on hover.

Context. A vocabulary specific to the project (stigmergy, compaction, DOMEX, ε-dispatch, sharpe-ratio).

Problem. Authors keep redefining the same terms inline because they don't trust the reader to know them. The redefinitions drift.

Forces. Defining once is fragile (reader hasn't seen it). Defining everywhere is duplicative (definitions diverge).

Therefore. Maintain a single glossary. Render hover-tooltips on every matched term across the site. Authors write the term plainly; the platform makes it self-explaining.

Where it shows up. docs/GLOSSARY.md + assets/glossary.js. The glossary file is both human-readable and the tooltip data source.

4. Pair every diagram with a level¶

L0, L1, L2 — same content, different resolution. Reader picks depth.

Context. Diagrams that try to do everything end up readable by nobody.

Problem. A 30-node mermaid graph is a visual wall. A 2-node graph oversimplifies. The right resolution depends on the reader.

Forces. Authors want to be complete. Readers want to be oriented.

Therefore. Every diagram declares a level. L0 is 1–2 nodes (the headline). L1 is 5–9 nodes (Miller's number — the shape). L2 is the full machinery. Most pages need only L0 and L1.

Where it shows up. docs/MERMAID-CONVENTIONS.md defines the rule. Used throughout.

5. Anchor abstractions in objects¶

Disco balls, tree rings, salmon, wedding rings — concrete things that compress big ideas.

Context. Pages about information theory, coordination, compression.

Problem. Abstract claims slide off the reader. "Stigmergy is coordination through traces" lands; "stigmergy is coordination through marks left in shared environment that other agents amplify or ignore" doesn't.

Forces. Precise definitions need many words. Memory hooks need few.

Therefore. For each abstraction, find one physical object that already embodies it, and mention the object first. The object carries the idea across; the precise definition is for re-derivation later.

Where it shows up. docs/FUN-FACTS.md is the concentrated form. Borrowed from Maggie Appleton's illustrated essays (her drawn anchor images do the same job) and from Bret Victor's "the medium is the message."

6. Sidenote, not footnote¶

Definitions, asides, and citations belong next to the prose, not at the bottom of the page.

Context. Long prose pages with non-trivial vocabulary or evidence.

Problem. Footnotes break reading flow: scroll down, find the note, scroll back. Inline parentheticals bloat the sentence. Removing the aside loses the citation.

Forces. Honest writing wants every claim sourced. Readable writing doesn't want every claim interrupted.

Therefore. Use margin sidenotes where the page width allows (Tufte CSS or pymdownx.details admonitions). On narrow viewports, collapse to expandable details. Either way: the aside is adjacent, not exiled.

Where it shows up. Currently uneven — most pages still use parenthetical asides. Migrating to the sidenote pattern is an open task.

7. Pull-quote the strongest line¶

If a page has one line that would make someone send the link to a friend, render it large and quotable.

Context. Pages with a memorable claim buried in the middle.

Problem. Readers skim. The best sentence in a 1500-word page is invisible without a scan-stopper.

Forces. Writers don't like to "highlight their own line." Readers can't find the highlight without it.

Therefore. When a page has a single strongest claim, lift it as a pull quote. Use a blockquote with no attribution; the page itself is the source.

Where it shows up. README.md implicitly ("the repo is the memory"). The convention isn't formal yet — adopting it is a near-term task. See also: aphorisms in docs/COMPRESSIONS.md.

8. Backlinks at the foot¶

Every page ends with "What links here."

Context. A networked set of concept pages.

Problem. Forward links are easy (you write them as you go). Reverse links — "what other pages refer to this one?" — are invisible without tooling, and they are exactly what tells the reader the surrounding context.

Forces. Maintaining backlinks by hand drifts. Without them, the graph is half-blind.

Therefore. Generate the back-link list at build time, render it at the foot of every page. The reader can always see who else thinks this concept is worth referencing.

Where it shows up. Not yet — proposed, blocked on a small build-time script. Tracked in docs/COMPRESSIONS.md. Borrowed from Roam/Obsidian's bidirectional-link convention; before that, from Niklas Luhmann's Zettelkasten.

9. Page card at the head¶

One card replaces three pieces of front-matter prose.

Context. A page that may be reached via search, a backlink, or a shared URL — the reader has not seen the surrounding nav.

Problem. A subtitle, a status line, a lede paragraph, and a TOC each sit in different shapes and locations. The reader has to assemble the "what is this page" answer from four scattered cues.

Forces. Each cue individually is small; the cost is the layout overhead of locating each one. Compressing them into one block makes scanning O(1) but risks losing the lightweight feel.

Therefore. Render a single page card under the H1: a one-sentence L0, status + tags as chips, a 3–5 node L0 mermaid, and 4 neighbour links labelled with one-line subtitles. Same component is intended to render as a search-result hit and as the related-block sidebar — built once, reused three places.

How to add one. Add a card: block to the page's frontmatter. The hook in tools/page_card_hook.py injects the rendered HTML right after the page's H1. No inline HTML in the markdown source — the markdown stays clean and diff-able.

---
card:
  l0: "One-sentence punchline."
  status: "🌿 budding"    # 🌱 seedling · 🌿 budding · 🌳 evergreen · 🪨 stub
  tended: "2026-05-08"
  tags: [topic, topic, topic]
  diagram: |
    flowchart LR
      a --> b --> c
  read_next:              # 4 neighbours, labelled
    - { href: "../sibling/", title: sibling, note: "one-line subtitle" }
  source: "Optional small attribution line below the card."
---

Every field is optional. The L0 mermaid carries the visual weight; we tried decorative glyphs and removed them — the diagram does the same job without the noise.

Where it shows up. docs/godding/stigmergy.md, docs/godding/brain.md, docs/godding/godding.md, docs/HUMAN-GUIDE.md, docs/investigations/STIGMERGY-IN-DAILY-LIFE.md. CSS in site_assets/assets/site-polish.css (.page-card-*). Borrowed directly from Maggie Appleton's digital-garden covers, with chips lifted from Alexander's pattern-card frontispiece.

10. Boost the front door¶

Search ranking is a curatorial act; default lunr ranks all pages equal.

Context. A site with ~150 markdown files, half autonomous-protocol and half human-readable. Lunr's BM25 ranking treats them all alike.

Problem. A reader searching "swarm" gets SWARM.md (a dense protocol document) before docs/godding/swarm.md (the plain-language explainer that's the actual front door).

Forces. You can't fix this by editing prose — both pages are correct text matches. You can fix it by telling the index which pages are the front door.

Therefore. Add search.boost frontmatter:

---
search:
  boost: 3      # canonical entry pages (README, MAP, HUMAN-GUIDE, godding/godding)
  boost: 2      # well-loved concept pages (GLOSSARY, FUN-FACTS, PATTERNS)
  boost: 0.3    # protocol / academic / autonomous (SWARM.md, CORE.md, PAPER.md)
---

Untagged pages get the default boost of 1. The convention is small and explicit: only tag pages that materially differ from default. A page that's average-human-readable doesn't need a boost.

Where it shows up. Applied to 17 files at the time of this writing (7×boost-3, 5×boost-2, 5×boost-0.3). When you create a new canonical entry page, add boost frontmatter; when you create a new internal-protocol page, de-rank it. Material for MkDocs reads this natively via the search plugin (no JS needed).

11. Tags as a corpus index¶

Cards declare what each page is about; the tag page reassembles them by topic.

Context. A site of N concept pages where each page commits to one concept. Pages don't naturally cluster by topic — but readers often arrive looking for a topic, not a concept.

Problem. A reader who wants to know "what does the site say about compression?" can't find out from the nav (organised by source-of-page, not topic) or from search (compression is mentioned 100 places, only a few are about compression). They have to read every page until they notice the pattern.

Forces. Adding a topic taxonomy to the nav clutters it. Tagging each page with topics works — but only if the tags then aggregate somewhere a reader can land on.

Therefore. Each carded page lists 3–5 tags: in its frontmatter. A build-time generator (tools/build_tags_page.py) reads them and writes docs/TAGS.md, grouped by tag with the page's L0 line as the inline summary. The page is regenerated on every build, so it never goes stale.

Where it shows up. docs/TAGS.md — currently 161 unique tags across 60+ carded pages. Borrowed from Wikipedia's category system and Andy Matuschak's tag-as-index practice; adapted to a flat one-page format suited to a small site.

How to add a pattern¶

Notice that you've solved the same writing problem on three different pages.
Name it.
Write a section here in the form: Context · Problem · Forces · Therefore · Where it shows up.
Link from at least one page that already uses the pattern.

A pattern with only one usage is premature; the threshold is three.