How to easily improve the quality of documentation and content

  •   3 minutes read
When we write documentation, it is helpful to have a tool for automating checks — preferably typos, spelling and grammar. These tools bring you more productivity.

Textlint

Textlint is a pluggable linting tool for text and Markdown. Its open-source utility, written in JavaScript. What does it do?

  • Checks validity of the hyperlinks.
  • Follows consistent terminology such as “JavaScript” vs “Java​script” or “npm” vs “NPM”.
  • Improves linguistic diversity by blocking words like just, easily or simply.
  • Indicates when TODO occurs, etc.
  • And much more with plugins.

Try Textlint

Installation and configuration in a project

  1. Installation

    npm i -D textlint
    npm i -D textlint-rule-common-misspellings
    npm i -D textlint-rule-no-dead-link
    npm i -D textlint-rule-terminology
    npm i -D textlint-rule-write-good
    
  2. Configuration file with rules .textlintrc.yml in the root of the project

    rules:
      terminology: true
      common-misspellings: true
      write-good:
        adverb: false
        passive: false
        tooWordy: false
        weasel: false
      no-dead-link: true
    
  3. Set shortcuts in package.json

    "scripts": {
      "text:lint": "textlint *.md",
      "text:fix": "textlint --fix *.md"
    }
    

Execute validation in CLI

npm run text:lint

Execute autocorrections in CLI

npm run text:fix

Proselint

A linter for prose — something like another grammar checker, but focuses on redundancy, jargon, illogicality, clichés, sexism, spelling, inconsistencies, oxymorons etc.. It’s written in Python with CLI and web API.

Try Proselint

Grammarly®

The most advanced grammar and linguistic tools follow correctness, clarity, engagement, delivery and style guide. Even the free (no paid) version is the most powerful and extremely easy to use. You can set goals for an audience, level of the formality (informal, neutral, formal), domain (academic, business, general. email etc.), tone (neutral, confident, urgent, analytical etc.), intent (inform, describe, tell a story etc.). Corrections show themselves as help with an explanation — one can learn something :-)

Try Grammarly®

The others

  • Ginger — direct competition from Grammarly, its nearly behind them.
  • Microsoft® Office — great spelling corrections, but it’s worse with grammar.
  • Google Docs — about half worse than MS Office.
  • Google Chrome — indicates errors (underlined in red) and grammatical deficiencies (grey underline) in text editing blocks. The proposed options are quite relevant and, most importantly, do not need to install or configure anything.
  • SpellCheckPlus — website, average results.
  • After the Deadline — site and library for developers, results not very convincing.

Conclusion

There are not many quality, automatic and affordable linting tools (analysis, checking, design and correction) of texts. Picking the right one depends on the use cases. Just choose for the needs from the tools above or try to find something more fitting to your needs :-) Grammarly Premium is my first choice for daily writing and email composition. Textlint becomes my bestie in my web development workflow.