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).

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."

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/.