How Atlas is written

Atlas has one job: describe our domain so that a person or an LLM seeing it for the first time understands it. That only works if the writing is plain. This page is the standard, and a linter enforces it (see the end).

The rule

Write every reader page for a smart person who has never seen this project.

• Plain language. Short, full sentences. One idea per sentence.
• Define a term before you use it. If a word is specific to us, say what it means the first time.
• No internal codes. No decision numbers, no window or session names, no ledger references. They mean nothing to a reader.
• No raw database IDs in the prose. If the exact table or column matters to a machine, put it in the data reference, clearly labelled, not in the sentence.
• No file.csv:line citations. Those are working notes, not a definition.
• Say what a thing IS and how it CONNECTS, in words. Numbers are welcome — just keep them plain ("about 2,400 companies and people"), and make sure they're real (checked against the live system, not remembered).

The counterweight — spend words where the idea is new (Joe, 24 August 2026)

The rule above is right and it was over-applied, on this very site, four times in a row. "Short sentences, one idea per sentence" got turned into "every block is short", and a page that is uniformly short can only name a new concept — it can never explain one. Naming without explaining is how jargon is made. Joe's verdict on the result: "Your carve", "Written on a piece", "Pieces that move" — "I have no idea what these mean."

So the standard has two halves, and the second one is not optional:

• Be terse where the thing is familiar. Most of a page is this.
• Be generous where the thing is new. A block that introduces a concept the reader has never met gets as many sentences as it takes. The walkthrough Joe liked best ran to eight sentences and 191 words where it introduced one new idea, and stayed at two sentences everywhere else.

Compression and plain language pull against each other. Making a page shorter raises its jargon per word, because the same concepts have to fit in fewer words. If a page is both too long and too jargony, shortening it will make the second problem worse. The way out is not fewer words — it is changing what the sentence is about.

The five moves, when you introduce a new idea

This is the shape of the explanation Joe found clearest, in order:

1. Start from something he already knows. "We used to have folders like '2D Animation'."
2. Say why the old way failed. "One video can be 2D and motion graphics at once — folders force a single home."
3. Name the new word as you define it, in the same breath. "A lens is the replacement: a saved search with a friendly name."
4. Show it working, with something real. "Show me everything whose craft is an animation category and that carries the 2D chip."
5. Then the reassurance. "Nothing new gets stored; the lens just knows where to look."

The failure mode is starting at move five. "Nothing new gets written on any piece" is a perfectly true sentence that means nothing to someone who was never walked through moves one to four.

How the July consoles speak (read as a reader, 25 August 2026)

The five moves are the shape. The consoles Joe liked also share a voice, checked against the source line by line (docs/reference/2026-08/2026-08-25/july-console-voice.md):

• Talk to him, in the second person, about his own past calls. "You asked whether UI Animation lives in motion graphics." "That's the grain law you already ratified, applied to a lens."
• Name a real thing he can picture on every decision. The Nike "Wild Planet" commercial; the two Sora clips; Filmograph's "Main Title Design".
• Give an honest opinion, and say when the data surprised you. "My take is no." "Here's what the data threw at us."
• State the alternative with its cost. "Simpler, but the moment beats become unfindable."
• Say what changes and what does not. "Nothing is stored or moved; reversible."
• Table labels are plain words, never coined nouns. "Fact / state", not "Your carve".
• Tell a surprise as a short story, numbers inside the sentence. "As a whole piece it's nearly empty — 3 items. As a moment inside other videos it's everywhere: 464 beats."

All seven cost words. That is why uniform brevity killed them.

The ratified voice, and "show it on real rows" (Joe, 25 August 2026)

Joe picked the voice from one decision written three ways: the walkthrough voice above (the five moves, second person, generous where the idea is new), with a scan-first table of plain questions on top. That is now the voice of every review surface.

He added a rule that is bigger than the voice: every decision shows itself on real rows. His words: "probe and use existing content/data/information to contextualize… this is what it is, this is what the decision impacts/changes." In practice a decision section carries:

• "This is what it is" — real pieces by name, and what is written on each one today and after. If the two columns are identical, say so; that is often the whole argument.
• "This is what it changes" — the impact, computed: how many pieces land where, what the saved views would show, which rules switch on. Counts come from a probe whose SQL sits on the file that generates the page, never from memory.
• "And what this call does to everything else written on the piece" — a piece carries brands, crafts, products, the job it does, themes, moments, a campaign. Show them, on the same real pieces, and say per relationship whether the decision changes it. Usually the honest answer is "no", and saying so on real rows is what makes the decision safe to confirm.
• Say exactly what you need back. One question in a box at the top; the answer as one line (CONFIRM · CHANGE: what you would change · LEAVE OPEN: what you still need to see); what happens on each. Repeat the syntax at the close — a reader who saw it once had lost it.
• The reference implementation is scripts/atlas-mechanism-page.py → mechanism-decision.html.

Write about the world, not about the machinery

The deepest version of the rule. Joe thinks in the things he can point at — a Nike ad, a campaign, a post on Instagram. Our machinery is labels, shelves, registries and migrations. A sentence about the machinery reads as jargon however plainly it is worded, because the reader has to hold our model in their head before it means anything.

Before: "Your carve — the same 64 labels, regrouped into 12 shelves." After: "You'd browse them in twelve groups instead of ten. The Nike ad is still a brand film either way."

The second one names a real thing and says what changes for the reader. Same fact, and no glossary needed. Which leads to the last rule: a glossary is a workaround for jargon, not a cure. When a reader flagged one of these coined phrases, the fix applied was to define it in a collapsed glossary. Defining jargon is not removing jargon.

Before / after

Before: "Actors → entity (2,438); company_type brand_owner 27 · product_line 394 · NULL 1,209 (DN-213). W2 folds this in." After: "We track about 2,400 companies, people, songs, and artists. Most are companies. Only a handful are labelled yet with what kind of company they are — a brand, an agency, a studio — so that labelling is still a work in progress."

Before: "The signal spine is wire-not-build; content_observations ~36k exists so the fork is partial." After: "We already store raw signals about content — about 36,000 observations. The pieces exist; the open question is how to connect them, not whether to build them."

Before: "Route by SOURCE CATEGORY (provenance), not just file format [source-pipeline.md:13-44]." After: "Decide how to handle a piece of content by where it came from — a brand's own site, a news outlet, a database — not just its file type."

The second rule — one kind of statement per page (DN-218)

Plain language is not enough on its own. A page also has to answer one kind of question, or the reader has to decide, sentence by sentence, whether they are reading a rule, a measurement, a defect, or a musing.

The test for anything you are about to write is: what would have to happen for this to change?

If it changes when…	it belongs in…
a decision is ratified	the model page
the pipeline runs	the generated state page (scripts/atlas-state.py)
the model and the live system disagree	a check (scripts/atlas-conformance.py) — never a paragraph
nothing yet — it is undecided	the questions ledger (decisions/open-questions.md)

So: a model page contains no unresolved question and no bare number. It names the vocabulary; it does not count the rows. It states the rules; it does not list today's exceptions. Each one ends with pointers to the other three surfaces, so the honesty is one click away and mechanically current instead of pasted in and rotting.

Two reasons this is a rule and not a preference. A number typed into prose starts lying the moment the pipeline runs, and nothing catches it — 68 of them had been written into these pages before this rule existed. And a defect written as prose reads as an opinion, goes stale silently, and nobody remembers to delete it once it is fixed; written as a check, it goes green by itself.

scripts/atlas-canon-check.sh enforces this and names the offending line, the same way Vale enforces the plain-language rule above.

The bar applies to EVERY surface, not just the model pages (Joe, 16 August 2026)

The linter only gates the reader pages, but the plain-speak bar is for the whole site — decision pages, proposal pages, reference pages, all of it. Joe's words: "embrace plain speak simple easy to understand approach to our writing for this atlas/docs always." In practice:

• Short cells. A table cell holds a phrase or two, not a paragraph. If a cell needs a paragraph, the content belongs in prose below the table.
• Narrow tables. At most four or five columns a reader actually sees. A table must never be cut off at the screen edge — merge columns or move detail into prose before adding a sixth.
• One idea per sentence, on every surface, dense reference pages included.

The review loop (Joe, 17 August 2026)

Three standing rules for every review round, so the site cannot quietly rot between them:

• Re-read every page, every round. A review round is not done until every existing page has been read against this standard and against what was just ruled — stale claims updated, ratified noise removed, naming made consistent. This page is part of that read.
• Every page must be reachable from the sidebar. A page that is only linked from chat or from another page's prose is a page Joe cannot find a week later. Review pages live in the collapsed "In review" group under Decisions; when one is ratified it retires per the proposal lifecycle, so the group never grows forever.
• Diagrams live only on sidebar-reachable pages. A map that exists on a lost page may as well not exist.

What this rule does NOT cover

The internal notes on this site (the build plan, the research notes, the status docs, the raw database census) are working documents, not the domain model. They keep their codes and shorthand — that's fine, they're for the people building this. They live under a clearly-marked "Internal notes" section so a reader knows they're not the map.

How it's enforced

A prose linter (Vale) checks every reader page (index.md and everything under pillars/) before a commit. It blocks internal codes, database IDs, and file:line citations, and nudges on a few jargon words. If you write "DN-213" or the raw database ID on a reader page, the commit fails. The rules live in .vale-styles/AtlasLegibility/.