Add latest changes from gitlab-org/gitlab@master

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&not[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**.