Improve the Issue Boards documentation
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.
Related issue: technical-writing#231 (closed)
Further details
As an example, here's the output from a Vale test on the issue_board.md file:
The numbers represent rows and columns, so for example
18:1
means "line 18, character no. 1".
issue_board.md
16:1 warning Shorter sentences improve gitlab.SentenceLength
readability (max 25 words).
27:1 warning Shorter sentences improve gitlab.SentenceLength
readability (max 25 words).
62:1 warning Use a comma before the last gitlab.OxfordComma
"and" or "or" in a list of
four or more items.
155:1 warning Shorter sentences improve gitlab.SentenceLength
readability (max 25 words).
164:1 warning Shorter sentences improve gitlab.SentenceLength
readability (max 25 words).
168:1 warning Shorter sentences improve gitlab.SentenceLength
readability (max 25 words).
172:1 warning Shorter sentences improve gitlab.SentenceLength
readability (max 25 words).
174:78 warning Shorter sentences improve gitlab.SentenceLength
readability (max 25 words).
196:1 warning Shorter sentences improve gitlab.SentenceLength
readability (max 25 words).
219:15 suggestion Avoid words like "currently" gitlab.CurrentStatus
that promise future changes.
231:7 warning Avoid using future tense: gitlab.FutureTense
"will automatically"
237:1 warning Shorter sentences improve gitlab.SentenceLength
readability (max 25 words).
237:73 warning Avoid using future tense: gitlab.FutureTense
"will no"
277:1 warning Shorter sentences improve gitlab.SentenceLength
readability (max 25 words).
283:1 warning Shorter sentences improve gitlab.SentenceLength
readability (max 25 words).
292:1 warning Shorter sentences improve gitlab.SentenceLength
readability (max 25 words).
318:1 warning Shorter sentences improve gitlab.SentenceLength
readability (max 25 words).
334:69 warning Avoid using future tense: gitlab.FutureTense
"will show"
392:70 warning Avoid using future tense: gitlab.FutureTense
"will be"
403:46 warning Avoid using future tense: gitlab.FutureTense
"will appear"
411:60 warning Avoid using future tense: gitlab.FutureTense
"will open"
431:23 warning Shorter sentences improve gitlab.SentenceLength
readability (max 25 words).
464:1 warning Shorter sentences improve gitlab.SentenceLength
readability (max 25 words).
469:1 warning Shorter sentences improve gitlab.SentenceLength
readability (max 25 words).
✖ 0 errors, 27 warnings and 1 suggestion in 1 file.
Proposal
Consider each or some error messages, and see if you can rewrite the noted file with a solution.
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 all of the issues, that is also OK, your contributions are still appreciated. And thank you!