better-clear-language

---
name: better-clear-language
license: MIT
description: Write in clear, simple (ASD-STE100 style) english.
---

# Better Clear Language

Write for a reader who must understand the text on the first pass. Preserve the source meaning, facts, citations, requirements, and level of certainty.

## Write the text

Use common words with precise meanings. Keep each sentence focused on one action or fact. Give instructions in the active voice and use the imperative when it fits.

Choose short sentences for actions. Use a longer sentence when it shows a necessary cause, condition, or time relationship. Vary the sentence form and length within each paragraph.

Keep one subject in each paragraph. Start with useful content. Place each reason or condition beside the statement that it controls. End the paragraph when the subject is complete.

Use lists for steps, options, fields, or checks. Choose the number of items from the content. Keep labels short. When the source has three distinct items, preserve all three without adding a rhythmic frame.

Define an uncommon term at its first use. Use the same term for the same thing throughout the text. Keep names, commands, code, quotations, and required legal terms exact.

## Apply the language limits

Remove these forms from the final text:

- Antithesis and contrasting pairs, including “not X but Y”
- Corrective negation that first states the wrong idea
- Several independent clauses placed side by side
- Repeated sentence frames within one paragraph
- Repeated openings, including negative anaphora
- Groups of three chosen for rhythm
- Setup and payoff structures
- Opening filler and closing summaries
- A final sentence that only repeats the paragraph
- Em dashes
- Stacked noun phrases
- Empty intensifiers, including “genuinely,” “really,” “truly,” and “actually”
- Corporate verbs, including “leverage,” “underscore,” and “reflect”
- Abstract nouns when a direct verb gives the same meaning
- Hedging that lacks a factual reason
- Stock transitions and rhetorical crutches
- Performative excitement

Keep necessary negation for warnings, limits, factual statements, and safety rules. State the limit once in direct language.

## Revise

Read the draft for meaning first. Resolve vague pronouns, hidden conditions, and missing actors.

Cut filler during a second pass. Replace complex words when a common word keeps the full meaning.

Check the rhythm last. Change repeated openings or matching sentence patterns. Split any sentence that makes the reader track separate actions.

Run `scripts/check_text.py <file>` when the output is in a local text file. Treat its results as mechanical checks. Review the remaining style rules by reading the text aloud.

## Resolve conflicts

Protect accuracy, safety, quoted text, code, and legal requirements before style. Keep a required technical term when a simpler word would change its meaning.