write-good

write good

Naive linter for English prose for developers who can't write good and wanna learn to do other stuff good too.

Use

npm install write-good

Important: Do not use this tool to be a jerk to other people about their writing.

API

writeGood is a function that takes a string and returns an array of suggestions.

var writeGood = require('write-good');

var suggestions = writeGood('So the cat was stolen.');

// suggestions:
//
// [{
//   reason: "omit 'So' from the beginning of sentences",
//   index: 0, offset: 2
// }, {
//   reason: "'was stolen' is passive voice",
//   index: 11, offset: 10
// }]

writeGood takes an optional second argument that allows you to disable certain checks.

You can disable checking for passive voice like this:

var writeGood = require('write-good');

var suggestions = writeGood('So the cat was stolen', { passive: false });
// suggestions: []

You can use the second argument's checks property to pass in custom checks instead of write-good's default linting configuration. Like this, you can check non-English documents, for example with the linter extension for German, schreib-gut:

var schreibGut = require('schreib-gut');

writeGood('Aller Wahrscheinlichkeit nach können Entwickler nicht gut schreiben', { weasel-words: false, checks: schreibGut });

// suggestions
// [{index : 0, offset : 29, reason : '"Aller Wahrscheinlichkeit nach" is wordy or unneeded' }]

You can use the second argument's whitelist property to pass in a list of strings to whitelist from suggestions. For example, normally only would be picked up as a bad word to use, but you might want to exempt read-only from that:

var writeGood = require('write-good');

var suggestions = writeGood('Never write read-only sentences.');
// suggestions: [{ index: 17, offset: 4, reason: '"only" can weaken meaning' }]

var filtered = writeGood('Never write read-only sentences.', { whitelist: ['read-only'] });
// filtered: []

CLI

You can use write-good as a command-line tool by installing it globally:

npm install -g write-good

If you have npm version 5.2.0 or later installed, you can use npx to run write-good without installing it:

npx write-good *.md

write-good takes a glob and prints suggestions to stdout:

$ write-good *.md

In README.md
=============
 = writeGood('So the cat was stolen.');
                         ^^^^^^^^^^
"was stolen" is passive voice on line 20 at column 40
-------------
//   suggestion: "'was stolen' is passive voice",
                   ^^^^^^^^^^
"was stolen" is passive voice on line 28 at column 19

You can run just specific checks like this:

write-good *.md --weasel --so

Or exclude checks like this:

write-good *.md --no-passive

Or include checks like this:

# E-Prime is disabled by default.
write-good *.md --yes-eprime

Note: The --yes prefix only works for E-Prime, because the other checks are included by default, anyway.

You can run just with text without supplying files:

write-good --text="It should have been defined there."

You can even supply multi-line text:

write-good --text="I can't see a problem there that's not been defined yet.
Should be defined again."

You can also pass other arguments:

write-good --text="It should have been defined there." --no-passive