Plain language
Reading-level target (Flesch-Kincaid ≤ grade 8 for body; ≤ 6 for primary actions and onboarding) + 5 mechanical rules that drop cognitive load for non-native speakers and cognitively diverse users. Mirrors USWDS plain-language mandate.
Spec — Plain language
*tatus* v0.1.0 — Draft. Mandatory across all Koder surfaces. Automated readability gate is follow-up tooling work.
R1 — Reading level target
| Surface | Flesch-Kincaid grade level (max) |
|---|---|
| Body copy | 8 |
| Primary actions, button labels | 6 |
| Onboarding / first-run | 6 |
| Error messages | 6 |
| Technical reference (API docs, spec pages) | 11 (technical readers OK) |
Measured perstring with the standard FleschKincaid formula (one score per i18n key). Strings exceeding the cap flag for rewrite — not a hard build failure in v0; tracked as drift count.
R2 — Prefer concrete to abstract
| Abstract (avoid) | Concrete (prefer) |
|---|---|
| "facilitate communication" | "talk" |
| "leverage capabilities" | "use features" |
| "implement modifications" | "change" |
| "in the event that" | "if" |
| "at this point in time" | "now" |
R3 — Prefer verbs to nominalized nouns
| Nominalized (avoid) | Verb (prefer) |
|---|---|
| "make a decision" | "decide" |
| "perform an analysis of" | "analyze" |
| "carry out an installation" | "install" |
| "provide a summary of" | "summarize" |
| "give consideration to" | "consider" |
Test: if a noun ends in -tion / -ment / -ance and is the object of a generic verb (make, perform, give, provide, carry out), there's usually a stronger verb.
R4 — Avoid Latin abbreviations
Already covered in grammarandmechanics.kmd R6; restated here because it's a top plain-language win.
- e.g. → for example
- i.e. → that is
- etc. → and so on
- via → through / using
- per → for each / according to
R5 — Define jargon at first use
- Technical terms (API, OAuth, JWT, MCP, RAG) MUST be either:
- Spelled out + abbreviation in parens on first use per surface, OR
- Wrapped in an inline
definition primitive (`specscomponentsinlinedefinition.kmd`).
- In onboarding / first-run, NO undefined jargon at all.
R6 — Use "you" not "users"
- "You can connect…" not "Users can connect…"
- "Your team" not "The user's team"
Exception: admin / policy / documentation contexts where the third-person is structural (e.g., spec text describing user behavior).
R7 — Examples (before / after)
| Before (FK ~ 14) | After (FK ~ 7) |
|---|---|
| "In the event that your authentication credentials cannot be validated, please ensure you have entered them correctly." | "If we can't sign you in, check your email and password and try again." |
| "This functionality enables the persistence of your work across sessions." | "This saves your work between sessions." |
| "Subsequent to the completion of the installation process, you may proceed to launch the application." | "After install, open the app." |
R8 — i18n
These rules govern English source strings. Each locale has its own reading-level conventions; translators adapt but should keep the same register (avoid academic register in body copy).
Não-escopo
- Automated readability gate in CI (follow-up tooling ticket).
- Per
locale FleschKincaid equivalents (esES INFLESZ, ptBR Adapted-FK). - Reading
level guidelines for marketing blog (ownercurated).