From 7fbac8fca57db5c0e9a2593851c8a622fb82ad6f Mon Sep 17 00:00:00 2001 From: Edwin van den Houdt Date: Thu, 27 Aug 2026 17:03:37 +0200 Subject: [PATCH] docs: write English prose in Simplified Technical English Adds a Conventions rule for Simplified Technical English (ASD-STE100). It covers documentation, code comments, commit messages, ADRs, and the backlog notes. STE is a controlled language. It makes text easy to read for people who do not have English as a first language, and easy to translate. The readers of this project are mostly non-native English readers. The rule states that STE governs form, not content. Split a long sentence. Never remove a caveat, a measurement, or a precise term to make text shorter. The rule does not apply to Dutch identifiers, $localize copy, quoted output, or existing documents that you are not already editing. It therefore does not change the Naming convention above it, which keeps domain contexts in Dutch. Co-Authored-By: Claude Opus 5 --- CLAUDE.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 88fa614..8bc7e7f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -214,6 +214,17 @@ regardless of which atomic layer it is (a context organism doesn't get its own - **Naming:** shared/reusable UI is **English** (language-agnostic: `button`, `wizard-shell`); domain contexts are **Dutch** (`registratie`, `herregistratie`, `*.machine.ts`). Pick the language by which side of the seam the code is on. +- **English prose uses Simplified Technical English (STE).** This covers documentation, + code comments, commit messages, ADRs, and the backlog notes. One idea per sentence; + 20 words or fewer in a procedure, 25 in a description. Active voice, present tense. + One word for one meaning — pick a term and repeat it, do not vary it for style. Keep + articles ("the test fails"). Three nouns together at most. No idioms and no humour. + Six sentences per paragraph at most. Write a procedure as numbered steps, one action + per step. + **STE governs form, not content.** Split a long sentence; never drop a caveat, a + measurement, or a precise term to make it shorter. + **STE does not apply to** Dutch identifiers, `$localize` copy, quoted output, or + existing documents you are not already editing. - **User-facing copy = `$localize`.** Every user-visible string is wrapped in Angular's first-party `$localize` (no third-party i18n lib), with a stable custom id (`` $localize`:@@context.key:Tekst` ``). Source locale is `nl`; a second locale is a