Skip to content

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

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!

Edited by Marcin Sedlak-Jakubowski