lint our prose

[kevinbarabash]

https://github.com/amperser/proselint/

[itsjohncs]

Oh wow, that's awesome. Would be super cool to integrate. I won't have to solicit proofreading from everyone on my contact list anymore :D!

[sloria]

Not sure if you are still considering this, but I can recommend vale, which uses proselint and other linters under the hood. It comes with a number of preset styles, e.g. 18F, MailChimp, The Economist, and allows you to create custom styles...like eslint shareable configs, but for prose.

[csilvers]

@jdkato shared a plan for vale in #74: turn it on for lint and make errors fatal.

I have no problem with that, assuming things like "word choice" and other stylistic issues aren't considered error-level problems.

One concern is what happens for warnings for things we decide not to fix (like its incorrect "correction" of "very very bad"). Will that show up every lint run for the end of time? Presumably we can suppress a lint check somehow -- how does that work? I don't want it to be more work to work around the linter than the benefit we get from it.

[sloria]

Yeah, I should have added a disclaimer to my recommendation: I've only used vale within my editor. I have not used it with CI, for exactly the concern @csilvers raises above. It's useful finding minor style improvements in the final drafting stages, but there's also a fair amount of noise (I usually end up ignoring many of suggestions).

[jdkato]

I have no problem with that, assuming things like "word choice" and other stylistic issues aren't considered error-level problems.

I think this may be the issue: as I mentioned in #74, Vale isn't a general purpose writing aid—it isn't proselint or Grammarly in the sense that they both claim to improve writing out-of-the-box. Vale, on the other hand, is designed to look for these stylistic issues.

Obviously, things like word repetition will never be 100% accurate (although some would argue that dealing with false positives in the editing phase is better than publishing true positives).

"Word choice" and other stylistic issues can be found with a high degree of accuracy but, to do so, Vale needs some sort of a writing standard to enforce (this is similar to how Python linters rely on PEP 8 and how Khan Academy lints its code). Many other projects and organizations have such a standard (e.g., 18F, OpenStack, jQuery, etc.)

It's useful finding minor style improvements in the final drafting stages, but there's also a fair amount of noise (I usually end up ignoring many of suggestions).

Vale's built-in rules try to be generally applicable but, as I've said above, to really benefit from Vale you need to go from thinking about what it suggests (all of which can be disabled) to using Vale to enforce your (or your organization's) own writing standards through its extension system.

---

In any case, I don't want to come across as a Vale evangelist; I designed the tool with the understanding that good writing can take many different forms.

If you decide to use it, I'd gladly help set it up. And if not, that's fine too.

EDIT: To answer your question about warnings, the best solution is probably Vale's contextual configuration, which allows you to disable Vale (or a specific rule) for only a certain section of text.