Implement Vale as a linter for Mautic docs
Closed this issue · 7 comments
Many Mautic contributors draft documentation without the knowledge of the Mautic documentation style and terminology guidelines. For many contributors, English is not the first language which makes contribution difficult and results in an inconsistent documentation.
We do not have dedicate writers to write or review contributions. To address this issue, we want to implement the Vale linter.
About Vale
Vale linter is an extension system/plugin that you can use in your git repo to enforce a standard editorial style guide that checks for syntax, grammar, and terminology when contributing to the documentation for Mautic. Vale is open-source and doesn't require installation of any programming language. It's a command-line tool and there's a desktop version for it as well. For CI purposes, it's best to use the command-line version. Many open-source organizations like Linode and GitLabs have successfully implemented Vale Linter and are happy about the results.
Steps to implement Vale in the Mautic doc repo
-
Create a solid style guide for Mautic (that includes all style, grammar, terminology checks that we want Vale to perform on any doc contributions). This will serve as the blue print.
-
Feed this style guide into Vale using YAML. Vale already comes with a set of styles that are implemented by default as soon you start using Vale in your git repo. These styles can be found here - https://github.com/errata-ai/vale/tree/v2/styles. In addition to the default style checks, we will need to add our own style checks based on the style guide for Mautic. Custom styles can be implemented as YAML configuration files.
-
Once we get an initial set of styles in place, we must setup a CI job that executes against each new Pull Request. The result is that every pull request we will run a check for Vale rules along with other existing checks. Issues will be flagged either as warnings or errors. We can switch a rule from warning to error by editing the configuration file. The check will only mark a PR as failing if there's something objectively wrong (that is if the rule is categorized as an error). The contributors will need to fix the errors to submit the PR .
Resources
git hub repo for vale - https://github.com/errata-ai/
Documentation for Vale: https://errata-ai.gitbook.io/vale/
How Vale fits into the CI cycle- https://github.com/marketplace/actions/vale-linter
@RCheesley and @npracht tagging you both here to get started on this.
Thanks for your work on this @swati-thacker13 - super excited to get this off the ground!
I wonder if we just kick off by using an existing styleguide (e.g. the Google ones seem to be pretty comprehensive and not a million miles away from our own styleguide).
Looping in @virgilwashere who wrote much of our styleguide and may also want to have some input on this!
@RCheesley, I agree with the idea of using the Google style guide. Among the publicly available styles for use by Vale here https://github.com/errata-ai/styles, there is an implementation of the Google Developer Documentation Style Guide. Can we start out with this? For terminology and capitalization specific to Mautic, we can add a few more YAML files later. Let's meet to discuss what the repo structure should be like and other details.
Yes, I think that would be a great start and we can refine as we go.
Great initiative @swati-thacker13! 🚀 Once you get to the point where it needs to be implemented in CI, feel free to ping me. Happy to help!
Great initiative @swati-thacker13! 🚀 Once you get to the point where it needs to be implemented in CI, feel free to ping me. Happy to help!
Thanks, @dennisameling! We'll soon need help with that.
Done so closing the issue! 🚀