Plain language

content specs/content/plain-language.kmd

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.

Quando esta spec se aplica

Triggers primários

Todos os triggers

Spec — Plain language

Status: v0.1.0 — Draft. Mandatory across all Koder surfaces. Automated readability gate is follow-up tooling work.

R1 — Reading level target

SurfaceFlesch-Kincaid grade level (max)
Body copy8
Primary actions, button labels6
Onboarding / first-run6
Error messages6
Technical reference (API docs, spec pages)11 (technical readers OK)

Measured per-string with the standard Flesch-Kincaid 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 grammar-and-mechanics.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 (specs/components/inline-definition.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 Flesch-Kincaid equivalents (es-ES INFLESZ, pt-BR Adapted-FK).
  • Reading-level guidelines for marketing blog (owner-curated).

Referências