plone
Consider using Vale for spellcheck and style guide
Plone Documentation versions affected
- [ ] 5.x
- [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.
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-.
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.
@ksuess @polyester do you have a preference for Vale configuration? I have no preference.
https://vale.sh/generator/
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.
I've added the following styles to my Vale.
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?
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
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-goodA -1 from me. I don't understand suggestions like886:16 suggestion Try to avoid using 'is'. write-good.E-Primefor a text likeOne tiny thing is still missing.ReadabilityScores? 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!
my /docs/.vale.ini
StylesPath = styles
MinAlertLevel = suggestion
Vocab = Base,Plone
Packages = Microsoft
[*]
BasedOnStyles = Vale, Microsoft
The lexicon
vocabulary/Plone/access.txtcomes in handy, as it is the key for typos in names.
Please share this file!
my
/docs/.vale.iniStylesPath = styles MinAlertLevel = suggestion Vocab = Base,Plone Packages = Microsoft [*] BasedOnStyles = Vale, Microsoft
Vocab = Base,Plone causes Vale to create two Vale vocabularies:
https://vale.sh/docs/vale-cli/structure/#vocab
Vocab is a special folder designed to supplement your styles. Each of its sub-folders—in this case, Base and Plone—contain two files: accept.txt and reject.txt.
These files allow you to control rule “exceptions” (such as what is considered a spelling error) without having to modify the style’s source itself
For testing purpose I added just some words to /docs/styles/Vocab/Plone/accept.txt:
Plone
Zope
Volto
Barceloneta
`plone.api`
`plone.restapi`
`plone.volto`
Getting closer.
Here's the .vale.ini so far.
StylesPath = styles
MinAlertLevel = suggestion
Vocab = Base,Plone
Packages = Microsoft
[*]
BasedOnStyles = Vale, Microsoft
And I started styles/Vocab/Plone/accept.txt, sorted.
Barceloneta
Plone
Volto
Zope
`plone.api`
`plone.restapi`
`plone.volto`
**/ works recursively from the root of a directory.
Vale cannot find the directories in submodules, or maybe ignores them via .gitignore. I don't know the reason. Anyway, specifying them works.
vale --no-wrap docs/**/*.md \
docs/volto/**/*.md \
docs/plone.api/**/*.md \
docs/plone.restapi/**/*.md
✖ 1865 errors, 848 warnings and 2968 suggestions in 254 files.
And on training:
✖ 4528 errors, 4397 warnings and 5777 suggestions in 451 files.
Happy holiday!
See discussion of RichText vs. rich text usage: https://github.com/plone/plone.volto/pull/106#pullrequestreview-1218192076