Writing Plain English

This convention applies to everything we write for each other: DBML notes, code comments, docs, GitHub issues, PR descriptions, review comments, and error messages. The team includes non-native English speakers. Write at roughly B1–B2 level: simple, concrete, direct. A document nobody can parse has zero value, even when it is technically correct.

Audience: every engineer and every AI assistant working in jodapp-api, jodapp-web, and this docs repo.

The rules

1. Short sentences. One idea per sentence. More than ~15 words — split it.
2. Common words. Say "cannot change", not "immutable". Say "copied from", not "snapshotted". Say "does nothing", not "no-op".
3. Active voice. "The system creates X", not "X is created by the system".
4. Bullets, never inline lists. Two or more items go on separate lines — not "there are 3 things: a, b, c".
5. No idioms or metaphors. They do not translate. Write the underlying meaning instead.
6. Explain, don't compress. Walk through the reasoning in full sentences so the reader learns the why. Plain words, full depth — simplifying the language never means dropping the technical content.
7. Concrete examples. "When a gig shift completes, we record $5 of the $20 platform fee as revenue" beats any abstract description.
8. Rules as tables. When stating a set of rules or conditions, use a small decision table instead of prose paragraphs. A table can be scanned in one pass; the same rules buried in a 130-word sentence cannot.

Words to avoid

Avoid	Use instead
immutable	cannot change
snapshotted	copied from
no-op	does nothing / has no effect
denormalised	copied into this table
idempotent	safe to run twice
load-bearing	important — removing it breaks X
red herring	looks like the cause, but is not
leaks into / cascades	spreads to
move the needle / north star / dial in	make a real difference / main goal / adjust

GitHub issues

1. Open with a short vocabulary list defining each table, column, and concept the issue uses ("an Org::Membership connects one Identities::User to one Org::Company").
2. Include a worked example — a numbered walk-through tracing one real person or value through the code.
3. Do not rely on initiative names ("employer sync Phase A 2.2") as context the reader must already know — state the rule itself. Assume the reader has zero context from prior conversations.

The check before committing prose

1. Read it aloud. Split any sentence over ~15 words.
2. Highlight every word that would not appear in basic technical English. Replace it, or define it on first use.
3. A comment block over ~6 lines — would bullets be clearer?