Bow Tie Kreative Writing System
Run the engine

Rules / clarity

CLR-002 Context default layer: word

Define necessary jargon

IF a domain term is necessary AND the intended reader may not know it, THEN define it at first use and use it consistently ELSE replace it with plain language.

Why the rule exists

A necessary term can teach; unnecessary jargon only transfers work to the reader.

Condition

The rule fires when this evaluates true. Paths marked below must be present in the fact base; the engine reports the rest rather than guessing them.

  • ALL
    • term.domain_specific eq true
    • term.necessary eq true
    • audience.term_familiarity in [low, unknown]

Facts this rule reads

PathSource
term.domain_specific You supply it
term.necessary You supply it
audience.term_familiarity You supply it

Then

  1. define — target term
  2. retain — target term

Else

  1. replace — target term

LAKA

Smallest sufficient intervention
Yes
Primary axes

Sources

  • Principles of plain language — Digital.gov / U.S. General Services Administration link
    Design content so the intended audience can find, understand, and use it.
  • Google Developer Documentation Style Guide — Google link
    Clear, consistent, audience-directed technical documentation.
  • Microsoft Writing Style Guide — Microsoft link
    Warm, clear, concise, helpful technical communication.
  • Developing Quality Technical Information — Michelle Carey; Moira Lanyi; Deirdre Longo; et al.
    Quality dimensions for usable technical information.
The raw rule record

Verbatim from 11-clarity-style-rules.json. Also available at /v1/rules/CLR-002.

{
  "id": "CLR-002",
  "name": "Define necessary jargon",
  "domain": "clarity",
  "layer": "word",
  "strength": "context_default",
  "human_logic": "IF a domain term is necessary AND the intended reader may not know it, THEN define it at first use and use it consistently ELSE replace it with plain language.",
  "when": {
    "all": [
      {
        "path": "term.domain_specific",
        "operator": "eq",
        "value": true
      },
      {
        "path": "term.necessary",
        "operator": "eq",
        "value": true
      },
      {
        "path": "audience.term_familiarity",
        "operator": "in",
        "value": [
          "low",
          "unknown"
        ]
      }
    ]
  },
  "then": [
    {
      "action": "define",
      "target": "term",
      "position": "first_use"
    },
    {
      "action": "retain",
      "target": "term",
      "require": "consistent_use"
    }
  ],
  "else": [
    {
      "action": "replace",
      "target": "term",
      "with": "plain_equivalent"
    }
  ],
  "unless": [],
  "because": "A necessary term can teach; unnecessary jargon only transfers work to the reader.",
  "diagnostics": [],
  "examples": {},
  "source_ids": [
    "WEB-002",
    "WEB-003",
    "WEB-004",
    "BK-024"
  ],
  "laka": {
    "smallest_sufficient_intervention": true,
    "primary_axes": [
      "scope",
      "depth",
      "magnitude",
      "reversibility"
    ]
  }
}

Other clarity rules

  1. CLR-001 Prefer the precise familiar word IF two words are equally accurate AND one is more familiar to the audience, THEN use the familiar word ELSE keep the precision-bearing term. Context default
  2. CLR-003 Expand unfamiliar abbreviations IF an abbreviation is not universally familiar to the audience, THEN spell it out at first use and pair it with the abbreviation ELSE retain. Context default
  3. CLR-004 One term per concept IF multiple terms refer to the same technical concept without rhetorical need, THEN select one preferred term and replace the variants ELSE retain. Context default
  4. CLR-005 One concept per term IF the same term denotes multiple concepts in one context, THEN rename or qualify the concepts ELSE retain. Hard constraint
  5. CLR-006 Replace vague reference words IF THIS, THAT, IT, THEY, FORMER, or LATTER has an uncertain referent, THEN repeat or summarize the referent ELSE retain. Hard constraint
  6. CLR-007 Quantify actionable vagueness IF vague quantity, frequency, time, or probability affects a decision, THEN provide a range, threshold, date, or defined category ELSE retain approximate language. Context default
  7. CLR-008 Use concrete examples after abstractions IF a central abstraction lacks a concrete instance AND the audience knowledge gap is moderate or large, THEN add one representative example ELSE retain. Heuristic
  8. CLR-009 State implied steps for novice readers IF success requires an unstated inference that a novice may not make, THEN state the step or prerequisite ELSE retain expert compression. Context default