Implement vale linter

[RCheesley]

Hi folks!

👋 Intro

This PR relates to #148 and implements the Vale linter to pick up spelling mistakes, grammar issues and potentially problematic word use.

I hope that this will help to iteratively improve the documentation and maintain quality going forward.

🤔 What's it doing?

Vale is a tool which lints - checks - text against certain pre-specified rules - much like similar tools for software development highlight and/or fix code style issues.

This helps to improve the quality of written text, pick up problems such as typos or grammar issues, and also can help to flag up words or phrases which might in some situations or cultures be inappropriate.

I have implemented two style plugins from Vale - Google and Alex.

Google's technical writers styleguide is a well-used developer technical style guide which covers a huge amount of grammar issues and best practices, and it also picks up some inappropriate word use.

Alex is more focused on the cultural sensitivity and appropriateness of words used.

This allows writers to check their text as they're writing (for example there are plugins for VSCode, PHPStorm etc) and it also allows us to check PRs which are made so that if we haven't fixed those files yet, they can be cleaned as we go and new contributions can be checked to ensure they adhere to the style guides.

✍️ Impact for writers

I have made one typo correction in a file and left another error in the same line, so that you can see what it looks like to the writer when they get feedback on their PR that something needs fixing:

In this case, you could replace the word 'execute' with something else that is not going to flag up a warning for being potentially problematic, for example 'implement'.

🛟 Considerations

Some things that I have found from using Google's styleguide in particular in the Mautic docs is that it does promote writing in the active voice rather than passive voice for documentation which can be tricky even for native English speakers at times (but ChatGPT is great at helping to convert text from passive to active and there's various resources online to help, too). So it might do well to have some documentation for writers who want to contribute, explaining what your style guide, tone of voice etc is, and how to deal with feedback about improving the grammar.

It is also possible to add your own specific words, for example 'Decidim', so that it's not flagged up as a typo and is always written in its capitalised form. Likewise you can also have words which will also flag up a failure - eg if people commonly mis-spell something.

I hope that this is helpful, I'm planning to work through some of the errors that are thrown up with it and make a PR by section to fix them (but they can also be fixed iteratively over time, too - doesn't have to be addressed straight away), in addition to the PR which addresses the gendered terms.

[andreslucena]

This is a great addition, specially for us that aren't English natives. We make lots of mistakes while writing, as you may've noticed 😅

I think that after we iron out the configuration for this (in a couple of months) we should also implement this on the main repository. I was thinking of at least the docs folder, as that includes some sections that are in https://docs.decidim.org

I have some suggestions before merging, can you please check them out? Thanks

[RCheesley]

Hi folks, sorry for the delay. Unfortunately, I badly broke my arm, so the last week has been a fun time of hospitals, surgery, and recovery! Hoping to get back to this over the next couple of weeks.

[RCheesley]

Ready for re-review - don't think the test failures relate to my changes.

[andreslucena]

👍🏽

[andreslucena]

Ignoring the failing check, as is unrelated to the current change set.

(Sorry for the delay with this one @RCheesley!!)