diff options
Diffstat (limited to 'doc/development/documentation/styleguide.md')
| -rw-r--r-- | doc/development/documentation/styleguide.md | 13 |
1 files changed, 9 insertions, 4 deletions
diff --git a/doc/development/documentation/styleguide.md b/doc/development/documentation/styleguide.md index fac0a581957..b604c94e016 100644 --- a/doc/development/documentation/styleguide.md +++ b/doc/development/documentation/styleguide.md @@ -212,7 +212,7 @@ Do not include the same information in multiple places. [Link to a SSOT instead. - Use inclusive language and avoid jargon, as well as uncommon words. The docs should be clear and easy to understand. -- Write in the 3rd person (use "we," "you," "us," "one," instead of "I" or "me"). +- Do not write in the first person singular. Instead of "I" or "me," use "we," "you," "us," or "one." - Be clear, concise, and stick to the goal of the doc. - Write in US English with US grammar. - Capitalize "G" and "L" in GitLab. @@ -230,18 +230,23 @@ Do not include the same information in multiple places. [Link to a SSOT instead. "Create a new merge request for Z." - Avoid use of the future tense: - - Instead of, "After you execute this command, the result will be displayed," say "After you execute this command, the result is displayed." + - Instead of "after you execute this command, GitLab will display the result", use "after you execute this command, GitLab displays the result". - Only use the future tense to convey when the action or result will actually occur at a future time. - Do not use contractions: - - Instead of "don't," "can't," "doesn't," and so on, say "do not," "cannot," or "does not." + - Instead of "don't," "can't," "doesn't," and so on, use "do not," "cannot," or "does not." - Possible exceptions are cases when a more familiar tone is desired, such as a blog post or other casual context. - Do not use slashes to clump different words together or as a replacement for the word "or": - - Instead of "and/or," consider saying "or," or use another sensible construction. + - Instead of "and/or," consider using "or," or use another sensible construction. - Other examples include "clone/fetch," author/assignee," and "namespace/repository name." Break apart any such instances in an appropriate way. - Exceptions to this rule include commonly accepted technical terms such as CI/CD, TCP/IP, and so on. - Do not use "may" and "might" interchangeably: - Use "might" to indicate the probability of something occurring. "If you skip this step, the import process might fail." - Use "may" to indicate giving permission for someone to do something, or consider using "can" instead. "You may select either option on this screen." Or, "you can select either option on this screen." +- We recommend avoiding Latin abbreviations, such as "e.g.," "i.e.," or "etc.," +as even native users of English might misunderstand them. + - Instead of "i.e.", use "that is." + - Instead of "e.g.", use "for example." + - Instead of "etc.", either use "and so on" or consider editing it out, since it can be vague. ## Text |