Automate editorial style checking

[juliamrch]

Checklist

• My PR is related to an opened issue : Nope

⚠️ If changes affect GitHub Action files

• I have added tests to cover my changes : Additional GitHub action on this repository Checks on a file on a test repo

Pull request type

Please check the type of change your PR introduces:

• Documentation content changes
• Bugfix on the site
• Build related changes
• Other (please describe): Automate editorial and spelling review with Vale

Description

A summary of the changes

This PR includes an additional GitHub Action with Vale integration. Vale is a documentation linter for editorial style and spelling to automate reviewing and ensure high quality content is merged.

It's configured as follows:

.vale.ini file to specify how to check the content:

StylesPath = .github/styles

Vocab = Doc

MinAlertLevel = suggestion

Packages = Hugo, Google

[*.md]
BasedOnStyles = Vale, Google
Google.Headings = NO

[*.xml]
Transform = docbook-xsl-snapshot/html/docbook.xsl

In the current file, Vale is configured as follows:

• Styles are placed in /.github/ to allow running Vale on local and on GitHub Actions runners as well.
• Vocabulary list contains Clever Cloud specific terms that should be enforced or ignored (ex: add-on is accepted while addon isn't).
• Good style is based on Vale built-in style rules and Google documentation style guide.
• Style reference for headings as specified by Google is ignored (because it flags emojis in titles, which we use)
• Support for .xml has been included, because our files contains it.

The workflow will run on Pull Requests and fail if the submitted content contains 1 error, then post the error directly on the review, like in this example:

The review scope is filtered by Reviewdog when running as a GitHub Action. It's been set to added in this PR, to consider only changes in the modified or added lines.

Further Customization

Vale can be tweaked and customized as we wish. We can add exceptions, specific vocabulary and rules that will suit our doc. This PR contains basic configuration that can be expanded.

Drawbacks

There are some limitations in Vale: some lines happen to be missed and the reviewdog action fails if Vale flags something as a warning (it should only fail on error). It's still in development and we could contribute to enhance it as well.

Why is this needed?

Writing good doc is hard but makes the reading easy. Memorizing all good practice principles and reviewing/enforcing them manually takes time and isn't an option if we want to allow everyone to contribute. Including this changes will allow us to:

• target specific problems and enforce accessibility and clarity only on submitted content from contributors, who won't need to read the whole guides to make quick changes or new pages
• give feedback on PRs immediately so the authors can start fixing issues as soon as they submit it

Reviewes

Who should review these changes? @cnivolle @davlgd

[github-actions]

Deployment has finished 👁️👄👁️ Your app is available here

[github-actions]

🚀 Your app has been updated and is available here

[github-actions]

🚀 Your app has been updated and is available here

[github-actions]

🚀 Your app has been updated and is available here

[github-actions]

🚀 Your app has been updated and is available here

[github-actions]

🚀 Your app has been updated and is available here

[cnivolle]

Tested and approved. Let's start with it now and refine the rules later. The suggestions given by Vale are helpful.

[davlgd]

LGTM, it's a good starting point. Maybe we can add a short mention to contributing rules and links to Vale, setup guide, list of integrations, etc. before merge.

After some tests it's good at spelling, but some rules are more annoying than useful and we'll need to choose what to keep or not in the coming weeks. But as they only appear as warnings, it's ok for now. For example, the future form is always marked as mistake to avoid with little informations on why, but when you look at the detailed rule on an external website, it tells... "it's ok if you talk about future" 😄 And I don't agree on some as the we/our rule in the Changelog context (can be used only after citing the org name).

So in the meantime, we should keep it clear that it's a first step with general rules we'll refine over time, and that contributor can choose to follow or not.

[github-actions]

🚀 Your app has been updated and is available here

[github-actions]

Your review app has been deleted 👋