Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Bring vale to warning level #1150

Open
aaronmondal opened this issue Jul 12, 2024 · 0 comments
Open

Bring vale to warning level #1150

aaronmondal opened this issue Jul 12, 2024 · 0 comments
Assignees
Labels
documentation Improvements or additions to documentation enhancement New feature or request good first issue Good for newcomers help wanted Extra attention is needed

Comments

@aaronmondal
Copy link
Member

At the moment we run vale in an error level configuration. This prevents many cases of typos and obvious phrasing issues, but doesn't fully enforce our style guidelines. We should improve the docs until vale passes with a warning-level configuration.

Perfectly following vale is not always the "correct" choice, but it'll give us a much better and overall more consistent baseline than what we have right now. The goal here is that the docs should read "as if they were written by one person with always the same, familiar tone" while being concise, inclusive and accessible to non-native speakers.

To make an improvement, enter the nix environment with nix develop, add a bogus word to e.g. the top-level readme (for instance, add "asdfasdf" or a duplicate word like "in in" to it somewhere). This causes vale to break on the pre-commit hooks. Then change this line to warning:

MinAlertLevel = error

You can then run pre-commit run -a to view all vale warnings.

I'll close this issue once we can enforce the warning level globally in CI.

This issue likely needs to be done over the course of multiple PRs. Many of these fixes are not hard to do, but fixing all docs is somewhat time-consuming. Contributions are welcome!

@aaronmondal aaronmondal added documentation Improvements or additions to documentation enhancement New feature or request help wanted Extra attention is needed good first issue Good for newcomers labels Jul 12, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation enhancement New feature or request good first issue Good for newcomers help wanted Extra attention is needed
Projects
None yet
Development

No branches or pull requests

6 participants