ongoing

README.markdown

@@ -1,48 +1,37 @@
 # vim-wordy
 
-> There are no bad words; only writers using good words poorly.
+> Writer’s tool for identifying potential problems in word usage
 
 ## Features of this plugin
 
-* A writer’s tool for identifying potential problems in word usage
 * Pure Vimscript; no external services or libraries needed
-* Leverages Vim’s native spell-check engine
+* Uses Vim’s native spell-check engine
 * Buffer-scoped configuration (leaves your global settings alone)
 
-That writing benefits from the effective use of words should be obvious.
-Without good word choice, your efforts at grammar, punctuation and
-rhetoric will be for naught, or rather squandered.
+## What is _wordy_?
 
-Effective usage means avoiding words that are lazy, weak, awkward,
-overused, imprecise, boring, abused, imprecise, redundant, or which merely
-serve as filler. Identifying and fixing such language serves as a central 
-challenge to each of us in our writing.
+_wordy_ is not a grammar checker. Nor is it a guide to proper word usage.
+Rather, _wordy_ is a rudimentary tool to assist writers in identifying
+words and phrases in their text that suffer from a history of misuse,
+abuse and overuse, at least according to usage experts.
 
-Because the goals of our writing are nearly as diverse as ourselves, there 
-is no single set of rules guiding usage. What stands for formal writing 
-will fail for informal. What’s needed for dialogue won’t jibe with that 
-needed for narrative. The demands placed on the technical writer aren’t 
-wholly shared by other writers of non-fiction.
+For example, if _wordy_ highlights ‘moreover’, a word for which there may
+be no good usage, a rewrite to eliminate it would be prudent. But if it
+highlights ‘therefore’ in a sentence, you may consider the usage worthy
+and elect to keep it, _wordy_ be damned.
 
-Works of prose evolve. We expect our first drafts to be saddled with poor 
-usage, full of weak and repetitive language to be culled on later 
-rewrites. With enough polishing a work can emerge for which we can be 
-proud.
+Existing proofreading software can scan your text for potential problems
+in grammar and usage and provide comprehensive feedback. However, some
+services require transmission of your work to a server for checking.
+Others require installation and configuration of a complex software
+package, where integration with your editor of choice may prove
+infeasible.
 
-Writers can benefit from tools which can help them along that path. 
-_wordy_ aspires to be such a tool.
+_wordy_ stands ready as a lightweight alternative to these comprehensive
+tools, focusing narrowly on identifying potential problems in usage.
 
-Existing proofreading software can scan your text for potential problems 
-in grammar and usage and provide comprehensive feedback. However, some 
-services like ‘After the Deadline’ require transmission of your work to 
-a server for checking. Others require installation and configuration of a 
-complex software package, where integration with Vim may prove difficult
-or infeasible.
-
-In contrast, _wordy_ stands as a lightweight alternative to these
-comprehensive tools, focusing narrowly on identifying potential problems
-in word usage. Because it’s primitive by comparison, it’s best used in
-concert with books and other resources on good usage in writing.
+_wordy_ is best used in concert with books and other resources on good
+usage in writing.
 
 ## Requirements
 
@@ -55,9 +44,8 @@ package manager.
 
 ## Configuration
 
-You’ll typically use this plugin on-demand. It does not require any 
-special configuration, unless you want to map its commands to keys. More 
-on that below.
+You’ll typically use this plugin on-demand. It does not require any
+special configuration.
 
 Important note: on the first use of each of the plugin’s dictionaries, 
 a spell file will be built. This produces a message that resembles: 
@@ -85,23 +73,7 @@ enter the command:
 :NoWordy
 ```
 
-## Usage Dictionaries
-
-_wordy_ can’t read your mind. Even if it could it couldn’t understand your
-intent. In fact _wordy_ is pretty dumb, as it will flag words and phrases
-that may fit your goals perfectly well. In such a case you can ignore
-_wordy’s_ protestations.
-
-_wordy_ errs on the side of identifying potential problems. For example,
-if it highlights ‘moreover’, a word for which there may be no good usage,
-you should consider a rewrite to eliminate it. But if it highlights
-‘therefore’ in a sentence, you may consider it worthy and elect to keep
-it, _wordy_ be damned.
-
-_wordy_ has a dozen dictionaries at the ready to attempt to shoot down
-your prose.
-
-### Weak and lazy words
+### Weak and lazy usage
 
 ``` 
 :LazyWordy
@@ -109,51 +81,30 @@ your prose.
 
 Lazy and weak words are common in first drafts.
 
-We sabotage ourselves though weak language.
-We defeat our goal of effective writing by kicking the legs out from
-beneath our verbs and tearing at the foundations of our nouns.
+We sabotage our writing though weak language, kicking the legs out from
+beneath our verbs and tearing at the foundations of our nouns, watering
+down the very points that we are trying to drive home.
 
-Words that water down the points we are trying to drive home.
+* “I _got_ up and _went_ to work.” (weak)
+* “I awoke and drove to work.” (better)
 
-“I _got_ up and _went_ to work.” => “I awoke and drove to work.”
+We diminish the weight of our ideas by adding modifiers and fillers.
 
-We diminish the weight of our ideas by adding modifiers.
+* “The regiment _that_ took the hill was _perhaps_ a hundred strong.” (weak)
+* “Despite heavy losses, the regiment took the hill.” (better)
 
-“The regiment was _perhaps_ a hundred strong, and took the hill.”
+Words can also be weakened through overuse.
 
-“The regiment took the hill, despite fewer than a hundred soldiers
-remaining in its ranks.”
-
-Text can also be weakened through overuse 
-
-“He _actually_ drove to work in the blizzard.” => “He drove to work in
-spite of the blizzard.”
-
-Use in rare occasions, effectively. Consult the books.
-
-Words can be fillers and play no active role, such as needless use of
-‘that’:
-
-“A dog that was missing an eye followed us.” => “A dog missing an eye
-followed us.”
-
-The use of ‘the’ can weaken, such as in this sentence. Better: start with
-“Using ‘the’”.
-
-You can use the word ‘have’ in situations where you can be more direct:
-“Can I have the ice cream?” => “I want ice cream.”
-
-Wordiness can be weak: “Joe _has the ability to_ eat beef.” => “Joe can
-eat beef.”
-
-Using forms of ‘to be’ when action verbs can be used. Covered as
-a separate target.
+* “He _actually_ drove to work in the blizzard.” (weak) 
+* “He drove to work in spite of the blizzard.” (better)
 
+When using this dictionary, scrutinize each highlighted word or phrase,
+asking whether it detracts from the point you are trying to make.
 
 ### Redundant phrases
 
 ``` 
-:RedundantWordy
+:WordyWordy
 ```
 
 Did you ever receive an ‘advance warning’ when a mere warning would do?
@@ -165,25 +116,32 @@ be redundant if some of the guests have crashed your event. Or dialect
 differences can erase redundancies, as the British will ‘protest against’
 where Americans may simply ‘protest’.
 
-To reveal [common redundancies][1] from which you can scrub from your
-prose, enter this command:
+### Puffery and Jargonese
 
-### WordyPuffery
+``` 
+:PuffWordy
+:JargoneseWordy
+```
 
-TODO describe puffery
-
-“The guru embodies authenticity; his disruptive ideas on
+“The man embodies authenticity; his disruptive ideas on
 self-actualization reflect his dynamic and transformative personality.”
+(puffery and jargonese)
 
-Instead of using these words, instead provide a graphic example.
+Instead of puffery, demonstrate through details.
 
-“The Empire State Building is enormously tall.” => “My ears popped several
-times during the X minute elevator ride to the observation deck.”
+* “The Empire State Building is breathtakingly tall.” (puffery)
+* “My ears popped several times during the minute-long elevator ride to 80th floor.” (better)
 
-### WordyCred
+### Manipulative language
 
-“Along with a growing body of evidence, because common sense insists that
-my opponent’s policies threaten and untrustworthy.”
+``` 
+:WeaselWordy
+```
+
+Words can be used to hide or obscure a weak position, as well as to cast
+doubt on a strong one.
+
+“Common sense will show that you can’t trust my opponent.”
 
 Rather than provide the reasoning and evidence, we’ll unconsciously sneak
 in weasel words to shore up a weak facade.