Merge branch 'eread/refactor-contractions-rules' into 'master'

Refactor contractions rules

Closes technical-writing#218

See merge request gitlab-org/gitlab!40687

doc/.vale/gitlab/ContractionsDiscard.yml

----
-# Suggestion: gitlab.ContractionsDiscard
-#
-# Suggests a list of agreed-upon contractions to discard.
-#
-# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
-extends: substitution
-message: 'Use "%s" instead of "%s", for a friendly, informal tone.'
-link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#language
-level: suggestion
-nonword: false
-ignorecase: true
-swap:
-
-  # Uncommon contractions are not ok
-  aren't: are not
-  couldn't: could not
-  didn't: did not
-  doesn't: does not
-  hasn't: has not
-  how's: how is
-  isn't: is not
-  shouldn't: should not
-  they're: they are
-  wasn't: was not
-  weren't: were not
-  we've: we have
-  what's: what is
-  when's: when is
-  where's: where is
-  who's: who is
-  why's: why is

doc/.vale/gitlab/ContractionsKeep.yml

----
-# Suggestion: gitlab.ContractionsKeep
-#
-# Suggests a list of agreed-upon contractions to keep.
-#
-# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
-extends: substitution
-message: 'Use "%s" instead of "%s", for a friendly, informal tone.'
-link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#language
-level: suggestion
-nonword: false
-ignorecase: true
-swap:
-
-  # Common contractions are ok
-  it is: it's
-  can not: can't
-  cannot: can't
-  do not: don't
-  have not: haven't
-  that is: that's
-  we are: we're
-  would not: wouldn't
-  you are: you're
-  you have: you've

doc/development/documentation/styleguide.md

@@ -540,35 +540,10 @@ tenses, words, and phrases:
 
 ### Contractions
 
-- Use common contractions when it helps create a friendly and informal tone,
-  especially in tutorials, instructional documentation, and
-  [user interfaces](https://design.gitlab.com/content/punctuation/#contractions).
-  (Tested in [`Contractions.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/Contractions.yml).)
-
-  <!-- vale gitlab.ContractionsKeep = NO -->
-  <!-- vale gitlab.ContractionsDiscard = NO -->
-  <!-- vale gitlab.FutureTense = NO -->
-  | Do       | Don't     |
-  |----------|-----------|
-  | it's     | it is     |
-  | can't    | cannot    |
-  | wouldn't | would not |
-  | you're   | you are   |
-  | you've   | you have  |
-  | haven't  | have not  |
-  | don't    | do not    |
-  | we're    | we are    |
-  | that's   | that is   |
-  | won't    | will not  |
-
-- Avoid less common contractions:
-
-  | Do           | Don't       |
-  |--------------|-------------|
-  | he would     | he'd        |
-  | it will      | it'll       |
-  | should have  | should've   |
-  | there would  | there'd     |
+Contractions can create a friendly and informal tone, especially in tutorials, instructional
+documentation, and [user interfaces](https://design.gitlab.com/content/punctuation/#contractions).
+
+Some contractions should be avoided:
 
 - Do not use contractions with a proper noun and a verb. For example:
 
@@ -580,13 +555,13 @@ tenses, words, and phrases:
 
   | Do                          | Don't                      |
   |-----------------------------|----------------------------|
-  | Do *not* install X with Y   | *Don't* install X with Y   |
+  | Do **not** install X with Y   | **Don't** install X with Y   |
 
 - Do not use contractions in reference documentation. For example:
 
   | Do                                       | Don't                                  |
   |------------------------------------------|----------------------------------------|
-  | Do *not* set a limit greater than 1000   | *Don't* set a limit greater than 1000  |
+  | Do **not** set a limit greater than 1000   | **Don't** set a limit greater than 1000  |
   | For `parameter1`, the default is 10      | For `parameter1`, the default's 10     |
 
 - Avoid contractions in error messages. Examples:
@@ -596,10 +571,6 @@ tenses, words, and phrases:
   | Requests to localhost are not allowed    | Requests to localhost aren't allowed |
   | Specified URL cannot be used             | Specified URL can't be used          |
 
-  <!-- vale gitlab.ContractionsKeep = YES -->
-  <!-- vale gitlab.ContractionsDiscard = YES -->
-  <!-- vale gitlab.FutureTense = YES -->
-
 ## Text
 
 - [Write in Markdown](#markdown).