Consider using Vale for spellcheck and style guide

[stevepiercy]

Plone Documentation versions affected

• 5.x
• 6.x

Description

Our current spellchecker is not well supported. For example, it will mark "add-on" as an incorrectly spelled word because it does not support hyphenation among other shortcomings. It also cannot be installed on M1 (and maybe M2) based macs.

@polyester suggested Vale as a replacement. I read its docs, and I am thoroughly impressed by its defaults, extensibility, and integration with editors and GitHub Actions as a Docker image.

If others agree, then I would implement it as a guide only to provide feedback to correct common misspellings and style errors, and suggest corrections. I would suggest that authors optionally run Vale after they have completed their first draft, allowing them to both "stay in the zone" and improve their writing quality.

[ksuess]

I like your suggestion to use Vale.
For testing I ran Vale against one chapter of the training.

 213:29   suggestion  In general, use active voice    Google.Passive      
                      instead of passive voice ('are                      
                      listed').                                           
 226:1    warning     Try to avoid using              Google.We           
                      first-person plural like 'We'.                 

Vale can help me writing better style like the both examples above illustrate.
The CLI is good for a final check. The VSCode extension is helpful while writing.

Apart from a tool for obeying style guides, I have a spell checker extension enabled in VSCode: "Code Spell Checker" from "Street Side Software" which is awesome.
"Quick fix": cmd-.

[stevepiercy]

Thanks for the feedback.

I also want to try it out before we decide which styles to adopt. Is the passive voice or first-person plural OK to use in some contexts? Trainings has a different context than Documentation, so perhaps "We" is OK in Trainings because we are working together and in person.

For VSCode, I think we should mention that extension in our contributing docs. PyCharm has a built-in spellchecker. Vale integrates with both, so we can add specific words to include or exclude in our spellcheck dictionaries.

Let's keep experimenting and get more feedback from authors. I think it is OK to suggest tools now so that authors can try them and so we can collect feedback from their use.

[stevepiercy]

@ksuess @polyester do you have a preference for Vale configuration? I have no preference.

https://vale.sh/generator/

• Google developer documentation
• Microsoft Writing Style Guide
• The Red Hat Style Guide

[polyester]

I have preference for Microsoft style guide - several reasons, but overall it's an easier one to work with /explain to non-native speakers and more attention to non-tech audiences.

[stevepiercy]

I've added the following styles to my Vale.

• Microsoft Writing Style Guide
• proselint
• readability
• write-good

Should I add or remove any?

For calling vale via make, I am currently listing all the directories with glob syntax, but it is not very clever.

vale docs/*.md \
    docs/backend/*.md \
    docs/backend/upgrading/*.md \
    docs/backend/upgrading/version-specific-migration/*.md
   # and so on

Is there a clever glob argument?

[stevepiercy]

Aha!

vale docs/**/*.md

[polyester]

I find the 'readability' warnings to be less than useful, they're all "try to keep the GobblediGook (x.y) Index below (z). Usually meaning your text is a bit convoluted, but not being specific. Line-by-line warnings are more useful, and are included in the others.

I would start with a small set, can always be added/changed later

[ksuess]

I've compared the base options on two chapters of my training.
The feedback is not the same but similar.
I would feel more comfortable with a style guide of MDN or another Free and Open Source organisation.
If I should choose one, than Microsoft.
I like for example their "Try to keep sentences short." 😉

I will use and enhance my training documentation with spell checking enabled in VSCode.
Reduce passive mode, especially.
But overall I'm pretty sure, that I will ignore lots of suggestions.
For example
658:63 suggestion Consider using 'change' instead of 'modify'. Microsoft.ComplexWords
Is 'modify' a complex word? I'm puzzled.

Plugins

• write-good
  A -1 from me. I don't understand suggestions like
  886:16 suggestion Try to avoid using 'is'. write-good.E-Prime
  for a text like
  One tiny thing is still missing.
• Readability
  Scores? I feel like in a competition. I prefer to keep in the flow… 😉

The lexicon vocabulary/Plone/access.txt comes in handy, as it is the key for typos in names.

Go for it!

[ksuess]

my /docs/.vale.ini

StylesPath = styles
MinAlertLevel = suggestion

Vocab = Base,Plone

Packages = Microsoft

[*]
BasedOnStyles = Vale, Microsoft