Repository metrics
- Stars
- (1,557 stars)
- PR merge metrics
- (PR metrics pending)
Description
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:
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!