[Docs] Fix warnings and suggestions from vale

[huong-li-nguyen]

Description

• Fix all warnings and suggestion from vale that were not visible until an error was introduced

---

@stichbury - returning to your comment on why certain things were not raised on Vale in the last PRs. I just quickly checked, and there are two relevant factors:

• Previously, e.g. was considered an error, but e.g was not -> I've made it stricter in this PR now
• It seems like vale as a pre-commit hook will always return "passed" as long as there is no new error introduced (3 different levels: error, warning, suggestion).

This means that over time, vale probably raised a couple of suggestions and warnings, but they were never shown to us unless we simultaneously introduced a vale error. To find all of the warnings/suggestions, I intentionally added an error (adding e.g. this in any of the docs) and then ran the linter. Only then were all of the warnings/suggestions visible. I've fixed them all in this PR now, but it's essential to be aware of that limitation.

@stichbury - I couldn't find a quick way of configuring that warnings/suggestions are also errors for us. Do you have an idea? Otherwise, it's good to be aware of the restriction above 🔝 It might be worth considering switching to github actions for vale. It seems like there is a configuration option fail_on_error that might does that, but one would have to test it out, because I am not sure if it behaves similarly to the pre-commit hook. So I'll leave that for someone to test out next sprint 👍

Screenshot

Notice

• I acknowledge and agree that by checking this box and clicking "Submit Pull Request":

  • I submit this contribution under the Apache 2.0 license and represent that I am entitled to do so on behalf of myself, my employer, or relevant third parties, as applicable.
  • I certify that (a) this contribution is my original creation and / or (b) to the extent it is not my original creation, I am authorized to submit this contribution on behalf of the original creator(s) or their licensees.
  • I certify that the use of this contribution as authorized by the Apache 2.0 license does not violate the intellectual property rights of anyone else.
  • I have not referenced individuals, products or companies in any commits, directly or indirectly.
  • I have not added data or restricted code in any commits, directly or indirectly.

[petar-qb]

🧹 😍

[stichbury]

Aha! That makes sense, thanks for working out what was happening and resolving those issues.

I couldn't find a quick way of configuring that warnings/suggestions are also errors for us. Do you have an idea?

We could just make the level setting of the Vale styles that are important into errors rather than warnings/suggestions? It's not non-trivial but it's relatively easy to do for the main culprits that we occur regularly such as spelling, capitalisation and abbreviation.

Of course, by doing that, it then means that all reports have to be fixed even where they are valid cases (this may mean simply switching vale on and off with comments around the section in question).

Having a way to see all suggestions clearly at all times, and then decide whether to act on them is the ideal. I'll discuss with @antonymilne in the next sprint as we have a ticket to look at this. For now though, you've cleared up what was there, and that's awesome. Thank you 🙏

[stichbury]

Nice modifications to make Vale happy, thank you! 🏆