diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2022-10-21 18:11:29 +0300 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2022-10-21 18:11:29 +0300 |
commit | 68613feb1d0df32fae0c1960368e517defc2b67d (patch) | |
tree | 1d0d68e3bf080567035323ee292097d16d5c836c /doc/development | |
parent | 559b1da28e46a9969315beb11ee2d2056f75b06d (diff) |
Add latest changes from gitlab-org/gitlab@master
Diffstat (limited to 'doc/development')
-rw-r--r-- | doc/development/documentation/styleguide/index.md | 23 | ||||
-rw-r--r-- | doc/development/documentation/styleguide/word_list.md | 26 |
2 files changed, 49 insertions, 0 deletions
diff --git a/doc/development/documentation/styleguide/index.md b/doc/development/documentation/styleguide/index.md index 042b49b119e..a35bbce773d 100644 --- a/doc/development/documentation/styleguide/index.md +++ b/doc/development/documentation/styleguide/index.md @@ -23,6 +23,13 @@ In addition to this page, the following resources can help you craft and contrib - [Google Developer Documentation Style Guide](https://developers.google.com/style) - [Recent updates to this guide](https://gitlab.com/dashboard/merge_requests?scope=all&state=merged&label_name[]=tw-style¬[label_name][]=docs%3A%3Afix) +## The GitLab voice + +At GitLab, we strive to be concise, direct, and precise. +Our goal is to provide information that's easy to search and scan. + +We want to be conversational but brief, friendly but succinct. + ## Documentation is the single source of truth (SSOT) The GitLab documentation is the SSOT for all @@ -125,6 +132,22 @@ Maintaining a knowledge base separate from the documentation would be against the documentation-first methodology, because the content would overlap with the documentation. +## Writing for localization + +The GitLab documentation is not localized, but we follow guidelines that +help benefit translation. For example, we: + +- Write in [active voice](word_list.md#active-voice). +- Write in [present tense](word_list.md#future-tense). +- Avoid words that can be translated incorrectly, like: + - [since and because](word_list.md#since) + - [once and after](word_list.md#once) +- Avoid [ing](word_list.md#-ing-words) words. + +[The GitLab voice](#the-gitlab-voice) dictates that we write clearly and directly, +and with translation in mind. [The word list](word_list.md) and our Vale rules +also aid in consistency, which is important for localization. + ## Markdown All GitLab documentation is written using [Markdown](https://en.wikipedia.org/wiki/Markdown). diff --git a/doc/development/documentation/styleguide/word_list.md b/doc/development/documentation/styleguide/word_list.md index ce9fd671a39..ce1ba5f2dc9 100644 --- a/doc/development/documentation/styleguide/word_list.md +++ b/doc/development/documentation/styleguide/word_list.md @@ -64,6 +64,23 @@ When you create a user, you choose an access level: **Regular**, **Auditor**, or Capitalize these words when you refer to the UI. Otherwise use lowercase. +## active voice + +Use active voice instead of passive. + +Use: + +- The contributor writes the documentation. + +Instead of: + +- The documentation is written by contributors. + +NOTE: +If you can add the phrase "by zombies" to the end of the sentence, +the construction is passive. For example, `The button is selected by zombies` +is passive. `Select the button` is active. + ## administrator Use **administrator access** instead of **admin** when talking about a user's access level. @@ -570,6 +587,15 @@ Do not use Latin abbreviations. Use **that is** instead. ([Vale](../testing.md#v Do not use **in order to**. Use **to** instead. ([Vale](../testing.md#vale) rule: [`Wordy.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/Wordy.yml)) +## -ing words + +Remove **-ing** words whenever possible. They can be difficult to translate, +and more precise terms are usually available. For example: + +- Instead of **The files using storage are deleted**, use **The files that use storage are deleted**. +- Instead of **Delete files using the Edit button**, use **Delete files by using the Edit button**. +- Instead of **Replicating your server is required**, use **You must replicate your server**. + ## issue Use lowercase for **issue**. |