quality-docs

A CLI tool to check the quality of writing in your project's markdown or plain text documentation.

This tool uses retext to check the quality of writing in your project's documentation using these plugins;

• retext-equality warns on insensitive, inconsiderate language.
• retext-intensify warns on filler, weasel and hedge words.
• remark-lint checks for proper markdown formatting.
• retext-readability checks the reading level of the whole document.
• retext-simplify warns on complicated phrases.
• retext-spell checks spelling against a US English dictionary and custom dictionary.

Table of Contents

• Installation
• Usage
  • Options
  • Reports
  • Custom Dictionary
  • Changing Default Config
• Troubleshooting
• Contribute
• License

Installation

Install the tool globally with npm to use the CLI.

npm install -g quality-docs

Usage

CLI

The CLI accepts one argument which is a glob of the documentation files you want to check. For example, to recursively check every .md file in your project;

quality-docs {,**/}*.md

Silent Mode

The -s, --silent flag enables silent mode which mutes warnings. Fatal errors are displayed in silent mode.

Config

The -c, --config flag passes in a JSON file with a custom config. The config is combined with default-config.json and the custom config overrides the defaults.

quality-docs {,**/}*.md --config custom-config.json

The override uses this format (without comments):

{
  "dictionaries": "sparkart.dic", // Path to custom dictionary file, relative to config file
  "rules": { // Turn rules on/off or change their severity
    "filler": {"severity": "warn"},
    "hedge": {"severity": "suggest"},
    "list-item-content-indent": false,
    "no-auto-link-without-protocol": false,
    "retext-readability": {
      "age": 18,
      "minWords": 7,
      "severity": "fatal"
    },
    "weasel": {"severity": "suggest"}
  },
  "ignore": [ // Words or phrases to ignore
    "can",
    "forward",
    "found",
    "start",
    "started",
    "up"
  ],
  "noIgnore": [ // Words or phrases ignored by default to not ignore
    "require",
    "transmit"
  ]
}

Ignore

When used along with the config flag, the -i, --ignore flag adds a word to the config file's ignore list. Example;

$ quality-docs {,**/}*.md --config custom-config.json --ignore irregardless
Added 'irregardless' to ignore list. Don't forget to commit the changes to custom-config.json.

Reports

The tool uses vfile-reporter to print a report of writing quality issues with their location and description. For example, a spelling error in README.md from line 76 column 119 to line 76 column 124 prints;

README.md
  76:119-76:124  error    thier is misspelled         spelling

Custom Dictionary

By default, quality-docs spell checks documents against a US English dictionary. To extend the built in dictionary with custom English terms related to your project(s), add a hunspell format .dic file to your project, and reference it with the customDictionary key in a custom config JSON file. See en_US-tech-industry.dic for an example. (Note: quality-docs uses the US English affix file to check for valid variants of dictionary words. Non-English characters or prefix/suffix rules are not supported.)

Changing Default Config

The quality-docs CLI ships with an opinionated configuration to improve your writing. If you want to override the defaults of the retext plugins used by this tool, we recommend one of these three options;

1. Exclude documentation files from the glob argument.
2. Use the --config flag to pass in a JSON file with default configuration overrides.
3. Use remark-message-control marks to turn on/off specific rules for individual documents or text nodes.

Troubleshooting

Here is a list of common confusing issues quality-docs flags, and how to resolve them;

Names are flagged as misspelled

If it's a common name, add it to a custom dictionary. If it isn't common or you don't want to add it to the dictionary, add it to the ignore array in a config override file.

Other non-dictionary terms are flagged as misspelled

Any non-dictionary terms in quotes are ignored. If the word is a literal value such as a variable name or package name, put it in backticks; `quality-docs`. If it's a made-up word or other literal representation of a non-dictionary term, use "buttonator" or 'buttonator'.

Table cells are flagged as being incorrectly padded

First, check the rules for formatting table cells in markdown. If everything is correct, check for empty table cells, which throw off the linter. Try adding content to blank cells; n/a or (none).

Another issue is being incorrectly flagged

Try using the methods provided to change the default config to suit your preferences. If custom config doesn't resolve the problem, file an issue including the text of the markdown file you're checking and the error you're seeing in the output.

Contribute

Open an issue to report bugs or ask questions. Open a PR to contribute. Run npm run test to make sure contributions pass the included tests.

License

MIT © 2016 Sparkart Group Inc.