A step written as a statement among instructions
step-statement-mixon by default (info)English
Numbered steps that mix statements (The tool asks) with orders (Run it)
Example
How to fix
Write what the reader does, as an instruction. If it describes a result, make it a second sentence of the step before, or move it out of the list.
Why it matters
A numbered procedure is a list of things for the reader to do. When "The installer asks for a password." sits among "Open the app." and "Run the installer.", the reader wonders whether that is a step to take too. In an English numbered list, chaff points at the few items that open with a subject and a verb (The installer asks, You click) among items that open with the verb. Japanese step endings (〜します / 〜してください against the rest) are checked by no-mixed-desumasu and list-item-form-mix, so this rule is for English only.
What it does not flag
Bulleted lists, procedures of fewer than three steps, numbered lists where instructions are half or fewer (a list of terms, or of cases such as a warranty's exclusions: "Faults caused by a drop"), short items ("Setup"), items with a label or an opening phrase before the verb ("Guests: …", "On the left bar, select …"), and procedures where statements are more than {limit} or not fewer than the instructions are not reported. Only the first sentence on each item's own line is read.
Turning it off or relaxing it
Technical details
- Layer
- L3
- Status
- stable
- Severity
- info
- Languages
- en
- Suited to
- technical, docs, blog, legal, academic, literature, speech
- Reads from the document
- pos
Levels
Set a level for this rule under rules in chaff.yaml. With nothing set, it runs at the level its genre gives it (see By genre below).
| strict | reported when 3 or fewer steps are statements and they are fewer than the instructions |
|---|---|
| normal | reported when 2 or fewer steps are statements and they are fewer than the instructions |
| relaxed | reported when 1 or fewer steps are statements and they are fewer than the instructions |
By genre
- Runs by default in
- technical/spec, technical/readme, blog/tech, blog/essay, blog/owned-media, docs/manual, docs/faq, docs/glossary
- Turned off by the genre in
- legal/contract, legal/statute, legal/judgment, legal/patent, academic/paper, literature/fiction, literature/essay, literature/poetry, literature/play, speech/address, speech/transcript
- Not suited to, and not run in
- business/proposal, business/report, business/email, business/press-release, business/meeting-notes
Message
This step is a statement that opens with its subject, unlike the other {count} instructions
Rewrite depth (chaff fix-plan --depth): light — words and sentences; the structure and the voice stay
This page is built from the rule's definition file:packages/chaff/rules/step-statement-mix.yaml