Writing for players: the editing passes' lessons, and the template written by them

The conventions gain a list of the habits players read as generated text
(a semicolon in every paragraph, statement-colon-explanation, "The" plus
an abstract noun as a heading, clipped fragments in threes, closing
aphorisms, "X, not Y", the page talking about itself), and of the errors
that come from inherited text: hidden information where there is none,
points where there are none, "both" at a larger table, unchecked claims,
and ledger-stored words reworded. new-game.sh points at the list.

The template follows it: the about link loses 'a labor of love', the
tabs are Origins and Games so far, and the hall, lobby, room, report
slip, table talk, guide and demo board read as Waving Hands' and
Hnefatafl's now do. The landing page and family.json carry the two
games' new taglines and lose their semicolons and the tip jar's aphorism.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0141G6xqLeNRYEtviLWSB5Up
This commit is contained in:
Eric Wagoner
2026-10-11 10:34:08 -04:00
co-authored by Claude Opus 5.5
parent f5b7416a9e
commit bbbe8ec312
13 changed files with 95 additions and 52 deletions
+53 -11
View File
@@ -11,10 +11,10 @@ README.
*Open a table*, *or join one* with a four-letter code, then *your games*
(the ledger of tables this browser holds a seat at, with whose move it
is and unread talk; for someone coming back it comes first, and finished
games wait further down), *your reports to the keeper*, and *about this game —
a labor of love*, which opens the about panel: a dialog of tabs (The
game, The tally, More games, Send word; a game may add its own, as Dip's
Playing here), `TabbedDialog.svelte`, with each game's words in its hall.
games wait further down), *your reports to the keeper*, and *about this game*,
which opens the about panel: a dialog of tabs (Origins, Games so far,
More games, Send word; a game may rename the first two in its own world,
as Waving Hands' Duels so far, or add its own, as Dip's Playing here), `TabbedDialog.svelte`, with each game's words in its hall.
The address names the dialog (`#about`, `#about/tally`), so a plain link
opens it; a game may put its guide and rules in dialogs the same way, as
Dip does. Its strip of tabs is `Tabs.svelte`.
@@ -86,8 +86,8 @@ README.
- **The hosting line** follows the family list in the about panel: the
games are free and will stay free, the servers cost a few dollars a
month, and ko-fi.com/kestrelsnest is where anyone may chip in. It says
nothing is unlocked by it and nothing withheld without it, and it
never names a game's rights holder: a tip is for the hosting, not the
every game stays whole either way, and it never names a game's rights
holder: a tip is for the hosting, not the
game.
- **Preferences** are what a browser remembers about its player: a panel
@@ -237,16 +237,58 @@ thing will happen), and the image carries it.
- **Our own words.** An older implementation's prose is a guide to the
tone, never a source to copy.
- **Plain chrome.** Headings, tabs, captions and notes say what is there
in ordinary words. Avoid the construction a label, a colon, then an
explanation ("The ledger: every gesture..."), and headings made of "The"
and an abstract noun ("The game", "The tally"); readers take both as the
mark of generated text. The images live in what happens, not in the
labels around it.
in ordinary words. The images live in what happens, not in the labels
around it. The patterns readers take as generated text are listed under
"Writing for players" below.
- **Changing text is not changing rules.** Chronicle wording is not part
of the ledger, so it ships without a rules revision; the deploy gate
compares outcomes, not sentences. A test that pins a phrase should pin
the fact inside it.
## Writing for players
Players have learned the habits of generated text, and once they spot one
they trust the rest of the page less. Every game built from this kit has
needed an editing pass to remove them. Write without them from the start,
and read each new page against this list before it ships.
- **One semicolon is fine. A semicolon in every paragraph is a tell.** Use
two sentences, or join with "and" or "so". Lists of rules may keep their
semicolons.
- **No statement, colon, explanation.** "The table is yours: seat a bot,
invite a friend" becomes "You can seat a bot or invite a friend". The
same goes for a label and a colon at the start of a line ("Shieldwall:
two or more pieces..."), and for a heading that ends in a colon.
- **No headings made of "The" and an abstract noun** ("The game", "The
tally"). Name what is there ("Origins", "Games so far").
- **No clipped fragments in threes.** "Four towers. One crown. No second
chances." Write one sentence instead.
- **No closing aphorisms.** A paragraph ends on its last fact, not on a line
meant to sound wise ("This is the whole art", "Nothing is unlocked by it
and nothing is withheld without it").
- **No "X, not Y" flourishes** ("drawn, not borrowed"). Say what it is.
- **No page that talks about itself.** Avoid "This page walks the room", "the
page keeps watch" and "a walk through the page". Describe the game and
what the player does.
- **No spaced em dashes** in the interface, and few anywhere.
- **Nothing copied from another game that is untrue here.** Text carried over
from the kit or a sibling game is the most common source of errors. Look
for hidden information in a game with none, points in a game without
them, a bot's name from another game, and "both" at a table that seats
more than two. Read every inherited line as if it were new.
- **Every claim checked.** A date, a count, "only" or "never" is checked
against the source and the engine. "A thousand years before chess" was
wrong, and so was "a shield is the only defence".
- **Words for any table size.** Use "every player" for what each does on a
turn, and plurals for opponents ("your rivals"), unless the game seats
exactly two.
- **Words the ledger stores are fixed.** An end-of-game reason written to a
ledger line is matched later by exact text. Rewording
one needs a migration, not just an edit.
The game's own voice (above) is not on this list. The chronicle's images,
the in-world names and the keeper are what the editing passes protect.
## The move
- **Every history reads top to bottom**, oldest first, and scrolls to the