Too many vague words
vague-word-densityon by default (info)Japanese / English
Too many vague words ("as appropriate", "as needed") for the length
Example
The rule measures the whole document, so this example was tried with an ordinary passage (about 200 words) after it that gives chaff nothing to report.
How to fix
Where it matters, say what, how far and by when: "report as needed" becomes "report every Friday", and "as appropriate" names the case.
Why it matters
"As appropriate", "as needed", "reasonable" and "in a timely manner" leave the reader to decide how far, how soon and what counts as done. One or two are ordinary; many leave much of the document to the reader, and two readers will fill it in differently. ISO/IEC/IEEE 29148 lists the same kind of word among those a requirement avoids. chaff speaks only when they are dense for the document's length. The words are listed in each language's lexicon.
What it does not flag
A few vague words for the document's length are not reported, and very short documents are not measured. Each sentence is reported once, and a word inside a longer phrase ("timely" in "in a timely manner") counts once. In legal documents, a word inside a term that law and practice define ("reasonable", "best efforts", "from time to time") is not counted. Inside a requirement, requirement-smell also reads "where possible" and "as needed". A word that the bracket right after it pins down ("a reasonable fee (USD 50)") is not counted either; a bracket that only names it ("(hereinafter the ""Fee"")") pins nothing down.
Turning it off or relaxing it
Technical details
- Layer
- L2
- Status
- stable
- Severity
- info
- Languages
- Japanese and English
- Suited to
- business, technical, blog, legal, docs, academic, literature, speech
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 | up to 2 vague words per 1000 words |
|---|---|
| normal | up to 4 vague words per 1000 words |
| relaxed | up to 8 vague words per 1000 words |
By genre
- Runs by default in
- technical/spec, technical/readme, blog/tech, blog/essay, blog/owned-media, business/proposal, business/report, business/email, business/press-release, business/meeting-notes, legal/contract, legal/statute, legal/judgment, legal/patent, docs/manual, docs/faq, docs/glossary, academic/paper, literature/fiction, literature/essay, literature/poetry, literature/play, speech/address, speech/transcript
Message
"{matched}" and other vague words: {density} per 1000 words (limit {limit})
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/vague-word-density.yaml