Check for unhelpful ‘assuming’ phrases such as 'just', 'simply' or 'obviously' with retext.

Using these phrases in documentation is unhelpful: “simple” is relative to a users’ knowledge and experience. Often it is fine to leave the phrase out completely:

Avoid:

“Simply run the tests. Just type npm test…”

But use:

“To run the tests type npm test…”

This plugin is based on the excellent retext (plugins) by Wooorm. Not much of this code is original and it probably could be much improved. PR's welcome 🚀

Install through npm:

npm install retext-assuming

Say we have the following file, example.txt:

You can just import an ES6 module.
Everything is simply Javascript.
Obviously you would need NodeJS > 8.
Actually, it's quite easy to use.

And our script, example.js, looks as follows:

var vfile = require('to-vfile');
var report = require('vfile-reporter');
var retext = require('retext');
var dontAssume = require('retext-assuming');

retext()
  .use(dontAssume)
  .process(vfile.readSync('example.txt'), function (err, file) {
    console.error(report(err || file));
  });

Should result in:

example.txt
   1:9-1:13  warning  Avoid “just”, it's not helpful       no-just       retext-assuming
  2:15-2:21  warning  Avoid “simply”, it's not helpful     no-simply     retext-assuming
   3:1-3:10  warning  Avoid “Obviously”, it's not helpful  no-obviously  retext-assuming
    4:1-4:9  warning  Avoid “Actually”, it's not helpful   no-actually   retext-assuming
  4:22-4:26  warning  Avoid “easy”, it's not helpful       no-easy       retext-assuming

⚠ 3 warnings

Checks for unhelpful phrases such as “just”, “simply” or “obviously” in processed text.

NOTE dontAssume is the assigned name of our required module. You can name it however you like.

Array.<string> — list of phrases to warn about (defaults to phrases.json)

Array.<string> — phrases not to warn about.

Boolean — If true includes matches that are probably fine (“You should not simply assume”)

• retext-equality — Check possible insensitive, inconsiderate language
• retext-intensify — Check for weak and mitigating wording
• retext-passive — Check passive voice
• retext-profanities — Check profane and vulgar wording

MIT © David Hund