mautic / mautic-documentation

User documentation for the Mautic project
https://docs.mautic.org
Apache License 2.0
20 stars 100 forks source link

Implement Vale as a linter for Mautic docs #145

Closed swati-thacker13 closed 3 years ago

swati-thacker13 commented 3 years ago

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

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

swati-thacker13 commented 3 years ago

@RCheesley and @npracht tagging you both here to get started on this.

RCheesley commented 3 years ago

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!

swati-thacker13 commented 3 years ago

@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.

RCheesley commented 3 years ago

Yes, I think that would be a great start and we can refine as we go.

dennisameling commented 3 years ago

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!

swati-thacker13 commented 3 years ago

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.

RCheesley commented 3 years ago

Done so closing the issue! 🚀