Evaluate, pick, and configure checking/linting tools for the Getting Involved Guide

Created a Google sheet to collect feedback on tool testing based on conversations in Slack and in previous ticket Develop writing style guidelines for the Getting Involved Guide

Anyone who would like to test a tool and report your findings, please request permission on this document, and I will add you as an editor. Content checking tool analysis

Some tools are mentioned above, but if you have other tools in mind, please feel free to add. You may also test a tool that someone else has already tested; it would be great to have feedback from different types of users (i.e., "personas"). For example, I tested Vale, but I am not a developer or comfortable with command line, so my perspective will be different than that of a developer/someone who is comfortable in command line.

Thoughts so far:

Vale has a smaller install footprint due to being golang. But it does not have as nice of editor integration that is available from the JavaScript tools such as textlint or alex. With that integration, then a user wouldn't need to use the CLI, but could use their editor of choice.

There is a vscode extension usable with vale.

Rules are easier to write in vale than textlint or alex, which require JavaScript knowledge.

textlint seems to be the most automatable, and it might take less time to implement an automated test that polls drupal.org's API by node and runs the linter on pages. I'm not sure if that's desirable, but it could be.

Added Hemingway app as a resource. It works well for grammar and readability checks.

It seems like textlint is much easier to integrate into a software js project so that all the rules can be installed from npm. This might make it difficult to integrate with editor software.

I wasn't able to get the vale vscode extension to do anything at all, but I may not have understood its documentation appropriately.

Edit: I figured out getting vale vscode to work, and it looks like it needs a local configuration file. Although npm may not be necessary to install rules it's still a directory and ini file that needs to be in the same directory. Again, this is editor configuration rather than automated or CLI access.

I tested in alexjs and vale, but gendered language used as a quote becomes a false positive lint error. This probably doesn't matter for documentation writing in these sections unless someone wants to write an inspirational quote.

Posted in the spreadsheet. Thank you, @mdstamm.

For textlint I used the following package.json, but I didn't try the many many node modules that are listed on the github page:

{
  "name": "blah",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "",
  "license": "GPLv2",
  "devDependencies": {
    "@textlint-rule/textlint-rule-no-unmatched-pair": "^1.0.7",
    "textlint": "^11.3.1",
    "textlint-rule-alex": "^1.3.1",
    "textlint-rule-diacritics": "^1.0.0",
    "textlint-rule-en-capitalization": "^2.0.2",
    "textlint-rule-spelling": "^0.1.1",
    "textlint-rule-unexpanded-acronym": "^1.2.3"
  }
}

One thing that I've experienced using automated linting tools like these for copy editing is that it can be helpful if you can configure rules to throw an error vs. a warning. For example; our style guide might say "Drupal vs. drupal". and if you ever write "drupal" it's an error. And is required to be fixed. But, a lot of the rules are bound to be subjective, and depend on specific context. For example, a tool linting for gendered language is going to flag words like "her", or "his". But, there might be legitimate reason to use them. These should show as a warning to the user, but not an error.

Especially if we're talking about doing any kind of automation where we would likely want the tool-chain disallow something that doesn't pass all the tests.

In my limited experience vale is the best for this as each rule can be configured to report as a suggestion, warning, or error.

Additionally we should consider whether the tool can process asciidoc content as it might be useful to also use the same tool-chain for the user guide and other "official" docs which are currently in asciidoc format.