ASD-STE100 Writing

1---
2name: asd-ste100-writing
3description: >
4  Write and audit clear user-facing copy with ASD-STE100 Simplified Technical
5  English. Lead with the reader's benefit. Use this skill for landing pages,
6  headlines, onboarding, messages, tooltips, docs, release notes, emails, and
7  product copy.
8---
9
10# STE Benefit Copy
11
12Two disciplines applied together:
13
141. **ASD-STE100 Simplified Technical English** — a controlled language spec (53 writing rules + an approved dictionary) built so that a reader with weak English still gets exactly one meaning from a sentence. It kills ambiguity.
152. **Benefit-first framing** — the reader does not want the capability. They want what the capability gives them back: freedom, peace of mind, time, power. Technical capability is evidence, never the headline.
16
17STE alone produces copy that is correct and dead. Benefit framing alone produces copy that is warm and vague. Do both.
18
19## Step 1: Classify the copy
20
21The rules tighten or loosen depending on what the text is. Pick one:
22
23| Mode | What it covers | Sentence cap | Voice |
24|---|---|---|---|
25| **Procedural** | Steps, instructions, setup guides, error recovery, safety notes | 20 words | Imperative, active only. No "you". |
26| **Descriptive** | Docs, explainers, tooltips, release notes, changelogs | 25 words | Active. Third person or "you". |
27| **Marketing** | Headlines, hero, feature blurbs, emails, landing pages | 25 words (headlines: 12) | Active, second person ("you") |
28
29Procedural and descriptive copy gets **strict STE**. Marketing copy gets **STE-informed** — every mechanical rule still applies, but a short approved list of benefit nouns (see `references/benefit-ladder.md`) is allowed even though they are not in the STE dictionary. This is a deliberate, bounded deviation. Do not widen it.
30
31## Step 2: Run the checker
32
33```bash
34python scripts/check_copy.py <file> --mode marketing
35```
36
37Modes: `procedural`, `descriptive`, `marketing`. Add `--json` for machine output.
38
39It flags sentence length, paragraph length, passive voice, `-ing` forms, noun clusters, unapproved words with substitutions, and marketing filler. It is a fast mechanical pass, not a judge — it catches maybe 70% of violations. Read the copy yourself for the rest.
40
41If no file exists yet, write the draft first, then check it. Never ship copy that has not been through the checker.
42
43## Step 3: Fix mechanically
44
45Work through the checker output. The rules that matter most, in order of how often they are broken:
46
47**One word, one meaning.** Each word carries a single approved sense across the whole document. If "monitor" is a noun somewhere, it is never a verb elsewhere. Pick one term per concept and never vary it for style — "sync", "synchronize", and "update" are three words, so they must be three different things.
48
49**One idea per sentence.** Split on every "and" that joins two thoughts. Split on every semicolon.
50
51**Active voice, verb early.** "The report is generated by the system" → "The system makes the report."
52
53**Simple tenses only.** Present, simple past, simple future. No perfect, no continuous. "We have been building" → "We build."
54
55**No `-ing` forms** unless part of a fixed technical name. "Booking engine" is a name and stays. "By connecting your calendar, you get..." → "Connect your calendar. You get..."
56
57**Max 3 nouns in a row.** "Property management channel sync failure" → "The channel sync failed for a property."
58
59**Keep articles and "that".** Do not compress by deleting function words. "Ensure setting enabled" → "Make sure that the setting is on."
60