Technical Writing — Simplified Technical English (STE)

Write clear, plain prose. These rules distill the high-value 20 percent of ASD-STE100 Issue 9 that prevents most writing problems. The full standard and dictionary are at `~/.kiro/steering/ste100/references/ASD-STE100_ISSUE9.pdf`.

Scope

Apply these rules to all prose that you write:

**Written deliverables** — docs, README files, commit messages, CR titles and descriptions, wiki pages, runbooks, API and design documents.
**Code documentation** — comments, docstrings, and inline explanations.
**Your own responses** — every reply, including explanations, reviews, and summaries.

STE controls the *form* of your sentences, not the content. When other guidance disagrees about form, follow STE. It still decides what you say and when you act. Keep the substance direct, then express it in STE.

Always

**Short sentences.** Maximum 20 words in procedures and instructions, 25 words in descriptions.
**One idea per sentence.** Give one instruction or one piece of information.
**Active voice.** "The scheduler starts the job," not "The job is started by the scheduler." Use the passive only when the agent is unknown ("The data is encrypted at rest").
**Imperative for instructions.** "Run the script," not "You should run the script."
**Condition first.** "If the test fails, check the log output," not the reverse.
**Articles before nouns.** "Open the configuration file," not "Open configuration file."
**Keep "that."** "Make sure that the service is running," not "Make sure the service is running."
**Same word for the same thing.** Do not use synonyms for variety. Reuse one term.
**Specific nouns over ambiguous pronouns.** If "it," "they," or "this" could point to more than one thing, name the thing.
**Inclusive, gender-neutral language.** Avoid "he," "she," "man," and "woman" unless necessary.
**Simple, common words.** Prefer short words. Technical nouns and verbs for your field are fine ("endpoint," "deploy," "shard").

Never

**No contractions.** Write "do not," "cannot," "will not" — even when the user uses them.
**No semicolons in prose.** Write two sentences instead. Semicolons stay correct inside code.
**No Latin abbreviations.** Write "for example," "that is," or list the items. Do not write "e.g.," "i.e.," or "etc."
**No phrasal verbs.** Replace with one precise verb. Write "extinguish," not "put out." Write "release," not "give off."
**No nominalized verbs.** "Apply the patch," not "Do the application of the patch."
**No wordy or Latinate padding.** See Common Fixes.

Common Fixes

| Instead of | Write | |-----------------------------|-----------------------------------------| | "In order to" | "To" | | "It is necessary to" | "You must" | | "Carry out the deployment" | "Deploy" or "Run the deployment" | | "Don't" / "can't" / "won't" | "Do not" / "cannot" / "will not" | | "Utilize" | "Use" | | "Execute" | "Do" (the STE dictionary rejects "execute") | | "Prior to" | "Before" | | "Subsequent to" | "After" | | "Terminate" | "Stop" | | "Initiate" | "Start" | | "i.e." / "e.g." / "etc." | "that is" / "for example" / list items | | Semicolons | Period, then a new sentence |

For the complete rule set (part-of-speech constraints, multi-word noun methods, safety-instruction format, word-counting rules, and the approved dictionary), consult the reference PDF above.