From 5012d78d01e8c6cc40714c8e57ce4e6f61276f24 Mon Sep 17 00:00:00 2001
From: Allie Sadler <102604716+aevesdocker@users.noreply.github.com>
Date: Wed, 17 May 2023 14:45:05 +0100
Subject: [PATCH] ENGDOCS-1366 (#17342)

* ENGDOCS-1366

* tidy and vale additions
---
 .github/vale/Docker/Substitute.yml    |  6 ++++
 contribute/style/formatting.md        | 10 ++++++
 contribute/style/grammar.md           | 10 +++---
 contribute/style/recommended-words.md | 47 +++++++++++++++++++++++++--
 4 files changed, 67 insertions(+), 6 deletions(-)

diff --git a/.github/vale/Docker/Substitute.yml b/.github/vale/Docker/Substitute.yml
index 9acd2d28a4..6dd93b3f0e 100644
--- a/.github/vale/Docker/Substitute.yml
+++ b/.github/vale/Docker/Substitute.yml
@@ -11,8 +11,12 @@ swap:
   (?:sign on|log on|log in): sign in
   above: previous
   adaptor: adapter
+  account name: username
   administrate: administer
+  admin: administrator
   afterwards: afterward
+  allow: let
+  allows: lets
   alphabetic: alphabetical
   alphanumerical: alphanumeric
   anti-aliasing: antialiasing
@@ -37,6 +41,8 @@ swap:
   mutices: mutexes
   paas: PaaS
   pb: PB
+  repo: repository
   scroll: navigate
   sign up: register
   tb: TB
+  wish: want
diff --git a/contribute/style/formatting.md b/contribute/style/formatting.md
index 0b4123f6bd..cfdb3c9ac8 100644
--- a/contribute/style/formatting.md
+++ b/contribute/style/formatting.md
@@ -156,3 +156,13 @@ Note that in many cases, an unordered list is sufficient to describe a list of i
 - To keep tables accessible and scannable, tables should not have any empty cells. If there is no otherwise meaningful value for a cell, consider entering N/A for ‘not applicable’ or None.
 
 For information on how to add tables to your content, see [Useful component and formatting examples](../components/tables.md).
+
+## Referring to file types
+
+When you're discussing a file type, use the formal name of the type. Do not use the filename extension to refer generically to the file type.
+
+    | Correct | Incorrect |
+    | --- | --- |
+    | a PNG file | a .png file |
+    | a Bash file | an .sh file |
+
diff --git a/contribute/style/grammar.md b/contribute/style/grammar.md
index 5e005588d4..4d64759d89 100644
--- a/contribute/style/grammar.md
+++ b/contribute/style/grammar.md
@@ -22,15 +22,15 @@ An initialism is a type of acronym that comprises a group of initial letters use
 - Don't use apostrophes for plural acronyms. ✅URLs ❌URL’S
 - Avoid using an acronym for the first time in a title or heading. If the first use of the acronym is in a title or heading, introduce the acronym (in parentheses, following the spelled-out term) in the first body text that follows.
 
-## Bolds and italics
+## Bold and italics
 
-Unless you're referring to Ul text or user-defined text, you should not add emphasis to text. Clear, front-loaded wording makes the subject of a sentence clear.
+Unless you're referring to UI text or user-defined text, you should not add emphasis to text. Clear, front-loaded wording makes the subject of a sentence clear.
 
 ### Best practice:
 
 - Don't use bold to refer to a feature name.
 - Use italics sparingly, as this type of formatting can be difficult to read in digital experiences.
-Notable exceptions are titles of articles, blog posts, or specifcation documents.
+Notable exceptions are titles of articles, blog posts, or specification documents.
 
 ## Capitalization
 
@@ -137,7 +137,9 @@ When you work with numbers in content, the best practices include:
 
 When writing version numbers for release notes, follow the example below:
 
-Version 4.8.2
+- version 4.8.2
+- v1.0
+- Docker Hub API v2
 
 ## Punctuation
 
diff --git a/contribute/style/recommended-words.md b/contribute/style/recommended-words.md
index 16bbc101c3..543a1c7630 100644
--- a/contribute/style/recommended-words.md
+++ b/contribute/style/recommended-words.md
@@ -6,6 +6,9 @@ keywords: recommended word list, style guide, contribute
 
 To help ensure consistency across our documentation, the Technical Writing team recommends these wording choices.
 
+#### & (ampersand)
+Don't use `&` instead of `and` in headings, text, navigation, UI copy, or tables of contents.
+
 #### above
 Try to avoid using `above` when referring to an example or table in a documentation page. If required, use `previous` instead. 
 
@@ -13,6 +16,21 @@ For example:
 
 _In the previous example, the dog had fleas._
 
+#### account name
+Don't use. Instead, use `username`.
+
+#### admin
+Write out `administrator` on first use. Use `admin` if it's the name of a UI label or other element.
+
+#### allows
+
+Don't use. Instead use `lets`.
+
+#### as of this writing
+
+Avoid because this phrase is implied. The phrase can also prematurely disclose product or feature strategy or inappropriately imply that a product or feature might change.
+
+
 #### below
 Try to avoid `below` when referring to an example or table in a documentation page. If required, use `following` instead.
 
@@ -58,6 +76,12 @@ Instead of:
 
 _In Docker Desktop 4.1 and lower._
 
+#### easy, easily
+What might be easy for you might not be easy for others. Try eliminating this word from the sentence because usually the same meaning can be conveyed without it.
+
+#### e.g.
+Don't use. Instead, use phrases like `for example` or `such as`.
+
 #### enable
 
 Do not use `enable`. Implies that disability is a less-desired or negative state.
@@ -68,6 +92,9 @@ Instead, use `turn on` or `toggle on`.
 
 Avoid where possible. Use `run` instead.
 
+#### K8s
+Do not use. Use `Kubernetes` instead.
+
 #### later
 Use `later` when talking about version numbers.
 
@@ -79,9 +106,16 @@ Instead of:
 
 _In Docker Desktop 4.1 and higher…_ or _In Docker Desktop 4.1 and above…_
 
+#### please
+
+Don't use `please` in the normal course of explaining how to use a product, even if you're explaining a difficult task. Also don't use the phrase `please note`.
+
 #### register
 Use `register` instead of sign up when talking about creating an account.
 
+#### repo
+Don't use. Instead, use `repository`.
+
 #### respectively
 Avoid `respectively` and be more precise instead.
 
@@ -92,6 +126,8 @@ Avoid. Use a verb phrase such as _move through_ or _navigate to_ instead, if the
 #### sign in
 Use `sign in` instead of `sign on` or `log on` or `log in`. If the user interface has different words, use those.
 
+Also use `sign in to` instead of `sign into`.
+
 
 #### sign up
 Use `register` or `create account` instead of `sign up` when talking about creating an account.
@@ -105,6 +141,10 @@ _Turn on the dark mode toggle._
 #### upgrade
 Use `upgrade` for when describing a higher subscription tier
 
+#### vs.
+Don't use `vs.` as an abbreviation for versus; instead, use the unabbreviated `versus`.
+
+
 #### we
 
 Try to avoid `we` and focus instead on how the user can accomplish something in Docker.
@@ -115,5 +155,8 @@ _Use widgets when you have work you want to organize._
 
 Instead of:
 
-_We created a feature for you to add widgets.
-One exception: You can use we recommend instead of it is recommended or Docker recommends._
+_We created a feature for you to add widgets._
+
+#### wish
+
+Don't use. Use `want` instead.