Improve CI settings doc based on Vale warnings/suggestions
Unless you're a Tichtov student, please do not take this issue, or create an MR for it.
Problem to solve
The Vale linter is used to support grammar linting in GitLab documentation. As Vale was implemented after many of the GitLab documents were written, we have many documentation pages that do not meet the linting standards created by the GitLab Technical Writing team for Vale.
Further details
As an example, here's the output from a Vale test on the doc/ci/pipelines/settings.md file:
ci/pipelines/settings.md
40:43 warning Avoid using future tense: gitlab.FutureTense
"will automatically"
43:65 warning Avoid using future tense: gitlab.FutureTense
"will fetch"
78:61 warning If possible, use "filename" gitlab.SubstitutionWarning
instead of "file name".
96:25 warning Avoid using future tense: gitlab.FutureTense
"will be"
100:1 warning Shorter sentences improve gitlab.SentenceLength
readability (max 25 words).
100:25 warning Avoid using future tense: gitlab.FutureTense
"will be"
112:26 warning Avoid using future tense: gitlab.FutureTense
"will be"
128:81 warning Avoid using future tense: gitlab.FutureTense
"will be"
143:1 warning Shorter sentences improve gitlab.SentenceLength
readability (max 25 words).
147:69 warning Spelling check: "csv"? gitlab.Spelling
153:1 warning Shorter sentences improve gitlab.SentenceLength
readability (max 25 words).
153:60 warning Avoid using future tense: gitlab.FutureTense
"won't be"
154:48 warning Avoid using future tense: gitlab.FutureTense
"will cause"
157:1 warning Shorter sentences improve gitlab.SentenceLength
readability (max 25 words).
159:28 warning Avoid using future tense: gitlab.FutureTense
"will strip"
175:84 warning Avoid using future tense: gitlab.FutureTense
"will have"
207:1 warning Shorter sentences improve gitlab.SentenceLength
readability (max 25 words).
207:29 warning "HEAD" has no definition. gitlab.Acronyms
216:89 warning Avoid using future tense: gitlab.FutureTense
"will be"
235:29 warning Avoid using future tense: gitlab.FutureTense
"will be"
242:57 warning Avoid using future tense: gitlab.FutureTense
"will be"
245:1 warning Shorter sentences improve gitlab.SentenceLength
readability (max 25 words).
280:19 warning Avoid using future tense: gitlab.FutureTense
"will be"
291:15 warning Avoid using future tense: gitlab.FutureTense
"will embed"
300:108 suggestion Avoid words like "Currently" gitlab.CurrentStatus
that promise future changes.
Each of these messages point to a specific line:column in the noted file.
Proposal
Consider each error message, and see if you can rewrite the noted file with a solution. You do NOT need to address all issues in the list, this is simply the full output from Vale.
Who can address the issue
Anyone with an understanding of basic written US English. Ideally, that person should also have some domain expertise in the subject area.
Additional notes
We appreciate any help that you can provide. If you cannot resolve some of the issues, that is OK, your contributions are still appreciated. And thank you!