Never present acronyms or initialisms in text shown to a user — spell them out.
Acronyms are coded jargon that make the app harder for new SES members to understand.
Capability labels in capabilities.json (and any UI copy) use the full name:
"Urban Search and Rescue" not "USAR", "Alpine Search and Rescue" not "Alpine
SAR". This applies even where an acronym was used historically. (Org/product names like
"SES" and "aXcelerate", and the source-data UoC codes themselves, are not the target —
this is about descriptive labels and prose.) Known outstanding violation: the report
still uses "FFR" ("By FFR", "Missing FFR") for "Fit for Role" — flag/track a cleanup
rather than leaving it; don't add new acronyms.
No violent or flippant Silicon-Valley-bro metaphor may ever appear in app text,
code, comments, commit messages, or docs — this is a hard ban, not a style
preference. Slipstream serves an emergency service whose members deal with
life-and-death situations; language that trivialises harm reads as unprofessional and
jarring for that audience, however normal it sounds in general software engineering.
The banned example this rule exists to prevent is the term "kill switch" (this file used to say it repeatedly, of all places).
Use neutral, literal wording instead. For the REMINDERS_SEND control specifically,
say "sending disabled", "sending is switched off", "sending paused (launch seeding)",
or "the sending control". This ban is enforced automatically by
slipstream/terminology-guard.test.ts, which scans every tracked text file for the
banned-phrase family and fails the build if one slips back in — see that file to add
further banned terms.
Everything you write — code comments, commit messages, pull request text, docs, and chat — must be readable by a smart 10th grader. This is not a style preference. A volunteer training officer, not a professional programmer, has to be able to read a comment and know what breaks if they change the line below it. Jargon hides meaning behind a word only the author already understood.
Say what actually happens, in plain words:
| Don't write | Write |
|---|---|
| "these tests are load-bearing" | "if you delete these tests, nothing will catch the mistake" |
| "the asymmetry runs the wrong way for safety" | "getting it wrong in this direction is dangerous; the other direction is only annoying" |
| "a member's swim cell is sensitive to the test's ceiling" | "a member's swim status only changes if their capability needs a higher swim level than their old test gives them" |
| "a code that would over-credit a member" | "a code that would tell a member they passed a test they never sat" |
| "first-class support", "leverage the cache", "orthogonal to" | "works the same as the others", "use the cache", "unrelated to" |
Rules of thumb:
- No metaphor borrowed from building, finance, war, or art criticism. If the sentence only makes sense to someone who already knows the answer, rewrite it.
- Say the consequence, not the category. "This is the only check that stops X" beats any adjective you could put in front of "test".
- A longer clear sentence beats a shorter clever one. Don't invent a noun to avoid writing a sentence.
- Real domain words are fine, and required — Fit for Role, Fit for Task, currency, capability, snapshot, claim. They come from NSW SES or this schema and mean something exact. Cut programmer culture words, not domain words.
- A few narrow technical terms this repo defines and relies on (fail closed, and the short forms in the CWE tests) stay — they're defined in Authn/authz testing and used consistently. Don't add new ones.
Related rules: no acronyms and no violent or flippant terminology, above. This one is not machine-enforced — no word list can catch a bad metaphor — so it's on the reviewer, and on you.