| **Before** | **After** |
- |:-----------:|:-----------:|
+ |-----------|-----------|
| Uh oh, spaghetti-o! We lost that one | We lost that page |
| Oops! We dropped the ball | We couldn't find that page |
| Huh, that's odd... | That page no longer exists |
@@ -154,7 +154,7 @@ To create effective 404 pages, follow these best practice guidelines:
| **Before** | **After** |
- |:-----------:|:-----------:|
+ |-----------|-----------|
| Your search came up empty | We can't find that page |
| The page you're trying to reach doesn't exist | That page no longer exists |
@@ -166,7 +166,7 @@ To create effective 404 pages, follow these best practice guidelines:
| **Before** | **After** |
- |:-----------:|:-----------:|
+ |-----------|-----------|
| That page doesn't exist. | Another page might have what you need, so try searching PatternFly. |
@@ -177,7 +177,7 @@ To create effective 404 pages, follow these best practice guidelines:
| **Before** | **After** |
- |:-----------:|:-----------:|
+ |-----------|-----------|
| **Error 404: Not found**
Requested URL not found on this server. Please try again. | **404: We couldn't find that page**
Another page might have what you need, so try searching PatternFly. |
@@ -188,7 +188,7 @@ To create effective 404 pages, follow these best practice guidelines:
| **Before** | **After** |
- |:-----------:|:-----------:|
+ |-----------|-----------|
| **404: Not all who wander are lost...**
But this page is. Search again or find your way back home. | **404: We lost that page**
Let's find you a better one. Try a new search or return home. |
diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/content/product-tours.md b/packages/documentation-site/patternfly-docs/content/design-guidelines/content/guided-tours.md
similarity index 77%
rename from packages/documentation-site/patternfly-docs/content/design-guidelines/content/product-tours.md
rename to packages/documentation-site/patternfly-docs/content/design-guidelines/content/guided-tours.md
index f4f87f6697..b9e817a94e 100644
--- a/packages/documentation-site/patternfly-docs/content/design-guidelines/content/product-tours.md
+++ b/packages/documentation-site/patternfly-docs/content/design-guidelines/content/guided-tours.md
@@ -1,12 +1,12 @@
---
-id: Product tours
+id: Guided tours
section: UX writing
---
-A product tour, also referred to as an "onboarding flow", includes a series of dialog boxes or pop-ups that introduce users to a new tool or a redesigned tool.
+A **guided tour**, also referred to as an onboarding flow or a product tour, includes a series of dialog boxes or pop-ups that introduce users to a new or redesigned tool.
-In product tours, your UX copy is never intended only to tell a user *how* something works. You need to convince them that using and learning about the product is worth their time.
+In guided tours, your UX copy is never intended only to tell a user *how* something works. You need to convince them that using and learning about the product is worth their time.
-When writing a product tour, refer to the following best practice guidelines and their respective before/after example:
+When writing a guided tour, refer to the following best practice guidelines and their respective before/after example:
1. **Focus on the user’s goals**: Emphasize what the user can do with the product.
diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/content/numerics.md b/packages/documentation-site/patternfly-docs/content/design-guidelines/content/numerics.md
index c694b70ce1..438408cd1e 100644
--- a/packages/documentation-site/patternfly-docs/content/design-guidelines/content/numerics.md
+++ b/packages/documentation-site/patternfly-docs/content/design-guidelines/content/numerics.md
@@ -19,7 +19,7 @@ PatternFly date and time formats follow the American standard. When localizing,
| 12-hour time notation | This time convention divides the 24 hours of the day into 2 periods of 12 hours, AM and PM.
12-hour time notation is the American standard. | 3:00 PM |
| 24-hour time notation | This time convention divides the day by 24 hours and runs from midnight to midnight. The hours are represented from 0 to 23. | 14:00 |
| Date and time | Include the timestamp, along with the timezone, after the date. | Thursday, January 21, 2019 9:38:11 PM EST
Thursday, 21 January 2019, 9:38:11 PM EST
07 Jan 2019, 23:33 UTC |
-| Time zone | Display time in the user's time zone or in UTC.
Use UTC when spanning multiple time zones. | Maintenance begins today at 14:00 UTC (2 PM EST). |
+| Time zone | Display time in the user's time zone or in UTC.
Use UTC when spanning multiple time zones.
Avoid mentioning if a time zone uses Standard Time or Daylight Saving Time. | Maintenance begins today at 14:00 UTC (2 PM EST). |
| Day |Write out the full name of the day. If space is limited, use the day’s 3-letter abbreviation:
| Monday, September 17, 2020
Mon, Sep 17, 2020 |
| Month | Write out the full name of the month. If space is limited, use the month’s 3-letter abbreviation.
- Jan
- Feb
- Mar
- Apr
- May
- Jun
- Jul
- Aug
- Sep
- Oct
- Nov
- Dec
| September 17, 2020
Sep 17, 2020 |
| Duration | HH:MM:SS or HH:MM | 03:15:30
03:15
00:15 |
diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/content/punctuation.md b/packages/documentation-site/patternfly-docs/content/design-guidelines/content/punctuation.md
index ad3c104b31..78e2eed448 100644
--- a/packages/documentation-site/patternfly-docs/content/design-guidelines/content/punctuation.md
+++ b/packages/documentation-site/patternfly-docs/content/design-guidelines/content/punctuation.md
@@ -3,95 +3,99 @@ id: Punctuation
section: UX writing
---
-## Headings and titles
-Headings and titles can include punctuation, but should not end in punctuation. For example:
+## Usage
-
-
-|**Before** | **After** |
-|------------|-----------|
-| Style, voice, and tone. | Style, voice, and tone |
-| Getting started with PatternFly! | Getting started with PatternFly |
+These best-practice recommendations cover some of the most common UI scenarios and use cases. For additional guidance, we also have recommendations for the use of specific [punctuation marks](#punctuation-marks).
-
+### Buttons
+Avoid using punctuation in button labels.
-The exception for this rule is a question mark, when it is contextually important. For example, in a confirmation dialog, it is important that users understand what action they are about to take. A valid heading may include a question mark, such as "Delete service account?".
+Do not use punctuation to create icons on buttons (for example, do not use a plus sign "+"). Instead, refer to [PatternFly's icons page](/design-foundations/icons) for any icons you place on buttons.
-## Referring to text in the UI
-When referring to an element or text in the UI, use bold text. Don't use quotation marks or italics -- those should be reserved for quotes and emphasis, respectively. For example:
+### Headings and titles
+Headings and titles can include punctuation, but should not end in punctuation.
-| **Before** | **After** |
-|------------------------------------|--------------------------------------|
-| Add user to the “Group title” team | Add user to the **Group title** team |
+| **Before** | **After** |
+|-------------|-----------|
+| Style, voice, and tone. | Style, voice, and tone |
+| Getting started with PatternFly! | Getting started with PatternFly |
-## Parallel structure
-All items in a list or series should be of the same part of speech. For example:
+The exception for this rule is a question mark (?), when it is contextually important. For example, in a confirmation dialog, it is important that users understand what action they are about to take. A valid heading may include a question mark, such as "Delete service account?".
+
+### UI text references
+When referring to an element or text in the UI, don't use quotation marks or italics. Those should be reserved for quotes and emphasis, respectively. Instead, use bold text.
-|**Before** | **After** |
+| **Before** | **After** |
|------------|-----------|
-| Remember these important tips: Write clearly; conduct research; spelling and grammar. | Remember these important tips: Write clearly; conduct research; use correct spelling and grammar. |
+| Add user to the “Group title” team | Add user to the **Group title** team |
-## Ampersand (&)
-For clarity, avoid using **ampersands** (&), and use "and" instead.
-
-## Buttons
-Avoid using punctuation on **buttons**.
+## Punctuation marks
-Do not use punctuation to create icons on buttons (for example, do not use a plus sign "+"). Instead, refer to [PatternFly's icons page](/design-foundations/icons) for any icons you place on buttons.
-
-## Colon and semicolon
-Use a **colon** to introduce a list or a series. You can also use it as a pause before introducing related information. For example:
+Follow these general guidelines when using punctuation marks anywhere in your UI.
-- "I enjoy the following hobbies: cooking, drawing, and traveling."
-- "That leads me to my favorite hobby: running."
+### Ampersand (&)
+An **ampersand** is a shorthand symbol for "and."
-Use a **semicolon** to connect two closely related independent clauses. You can also use a semicolon instead of a comma to separate long list items for extra clarity. For example:
+For clarity, avoid using ampersands. Use "and" instead.
-- "I love running in the morning; it wakes me up."
-- "Every morning, I enjoy eating toast, bacon, and eggs; reading a book; and relaxing on the porch."
+The exception to this is within graphics or when you have particularly limited space in the UI.
-**Note**: If you're tempted to use a semicolon in the UI, try breaking up the sentence and cutting down on your words instead. This often leads to content that is more readable and clear.
+### Colon (:) and semicolon (;)
+#### Colon
+A **colon** separates parts of a sentence.
-## Commas
-When a conjunction connects two independent clauses, a **comma** should precede it. Also put a comma before “and” if it’s the Oxford comma. For example:
+| **Guideline** | **Examples** |
+|------------|-----------|
+| Use a colon to introduce a list or a series. | "The product improved in 3 categories: accessibility, ease of use, and functions."
+| Use a colon after a note label.| "Note: By the way, this note may be good to know."
"Tip: Here's a helpful tip for you."
+| Use a colon between 2 independent clauses to elaborate or emphasize a relationship between the clauses.\*
\* This usage is typically interchangeable with an [em dash](#em-dash-). | "Plan the configuration carefully: the initial settings are difficult to change after you add user accounts."
-- "I like to run, and I like to swim" — A comma is needed before “and” because “and” connects two independent clauses.
-- "I like to run and swim: — A comma is not needed before “and” because “and” does not connect two independent clauses.
-- "I like to run, swim, and hike" — The Oxford comma is included before “and.”
+#### Semicolon
+A **semicolon** indicates a firm break or pause in a sentence.
-## Ellipses (...)
-**Ellipses (...)** are commonly used when information is omitted. Use ellipses when you cannot fit all words onto a line or when you remove less relevant information (like in a quote). For example:
+| **Guideline** | **Examples** |
+|------------|-----------|
+| Use a semicolon to connect two closely related independent clauses.| "I love running in the morning; it wakes me up."|
+ You can also use a semicolon instead of a comma to separate long list items for extra clarity. | "Every morning, I enjoy eating toast, bacon, and eggs; reading a book; and relaxing on the porch."
-
+If you're tempted to use a semicolon in the UI, try breaking up the sentence and cutting down on your words instead. This often leads to content that is more readable and clear.
-|**Before** | **After** |
-|---------------------|--------------------|
-| They said, “For many reasons, I think the PatternFly community is great.” | They said, “...I think the PatternFly community is great.” |
+### Comma (,)
+A **comma** indicates a break or pause in a sentence.
-
+| **Guideline** | **Examples** |
+|------------|-----------|
+| Use a comma before a conjunction if it connects 2 independent clauses. | "Click **Save**, and type a file name."|
+| Use a comma between items in a list of 3 or more words or phrases.| "A message window describes an error, explains how to correct it, and provides the controls to correct it."
+| Use the Oxford comma, which is placed before the conjunction in a list of 3 or more words or phrases. |"I like to run, swim, and hike."
+Use commas after introductory words and phrases. | "First, create a project."
"After you remove the lid, proceed to step 4."
+| Use commas to separate nonrestrictive clauses (clauses that provide additional, nonessential information).| "The Recovery log, which is generated automatically, shows the cause of the problem."
-Ellipses can also be used in more creative contexts to signify someone’s thoughts or speech, like a pause for thinking. For example, "But I was just trying to...never mind, forget it."
+### Ellipsis (...)
+An **ellipsis** is used when information is omitted from a sentence or phrase.
-## Em dash, en dash, and hyphen
+In a UI, ellipses are most commonly used for truncating text. Refer to our [truncation guidelines](/ux-writing/truncation) for these scenarios.
-### Em dash ( — )
-To add emphasis to a phrase or sentence following it, use an **em dash ( — )**. You can also use an em dash to provide additional information or specification in the middle of a sentence. For example:
+### Dashes and hyphens
-- "Good design is not about you—it’s about the user."
-- "I like drinking something hot—coffee, tea, or cocoa—during my morning meetings."
+#### Em dash (—)
+An **em dash** is used to add emphasis to a phrase or sentence. You can also use an em dash to provide additional information or specification in the middle of a sentence. For example:
+- "Good design is not about you—it’s about the user."
+- "I like drinking something hot—coffee, tea, or cocoa—during my morning meetings."
-### En dash ( – )
-To separate numbers in a series, use an **en dash ( – )**. For example, "We plan on having 100–150 attendees."
+#### En dash (–)
+To separate numbers in a series, use an **en dash ( – )**. For example:
+- "We plan on having 100–150 attendees."
-### Hyphen ( - )
+#### Hyphen (-)
Use a **hyphen ( - )** if it's part of a term (such as "walk-through") or someone's name (such as "Mary-Jane").
You should also use a hyphen for a compound adjective that comes before the noun it modifies, but omit the hyphen if the first adjective ends in "-ly." For example:
@@ -101,21 +105,30 @@ You should also use a hyphen for a compound adjective that comes before the noun
- "He is a highly talented writer."
- "She is a high-quality job candidate."
-For most prefixes, you should *not* use a hyphen. For example:
+For most prefixes, you should *not* use a hyphen. However, there are a few scenarios where using a hyphen with a prefix is appropriate.
-- Auto- (such as autopopulate; autoloading)
-- Pre- (such as prerequisite)
-- Re- (such as recreate)
-- Sub- (such as submerge)
-
-An exception for this rule is when you add a modifier prefix like “non." In these cases, you should use a hyphen. For example, "non-Red Hatter."
+| **Guideline** | **Examples** |
+|------------|-----------|
+| Use a prefix hyphen to distinguish the word from a homonym. | "co-op"
"re-create" |
+| Use a prefix hyphen when the root word is capitalized or is a numeral. | "pre-2000" |
+| Use a prefix hyphen when the root word consists of more than one word. | "non-English-speaking citizens"
"pre-latency-period transaction" |
+| Use a prefix hyphen when identical letters would be next to each other. | "co-opt"
"de-emphasize"
+| Use a prefix hyphen when the prefix is "self-", "all-", or "ex-" (meaning formerly.) |
+
+With caution, there are some instances where you can use a prefix hyphen when the prefix is "non":
+- When it precedes multiple words. For example:
+ - "non-Red Hatter"
+ - When omitting a hyphen would impede readability. For example:
+ - "non-native"
If you're unsure about the use of a hyphen, refer to [Merriam-Webster's online dictionary.](https://www.merriam-webster.com/)
-## Exclamation mark
-Use **exclamation marks** sparingly. Don’t use one to generate excitement; only use an exclamation mark if the user is actually experiencing something exciting. You can also use an exclamation mark for something cautionary, like “Stop!” or “Watch out!”
+### Exclamation mark (!)
+An **exclamation mark** is used to denote excitement.
-To more accurately capture human expression, use an exclamation mark after just a few words, not after a long sentence. For example:
+Use exclamations marks sparingly. Don’t use one to generate excitement; only use an exclamation mark if the user is actually experiencing something exciting. You can also use an exclamation mark for something cautionary, like “Stop!” or “Watch out!”
+
+To more accurately capture human expression, use an exclamation mark after just a few words, not after a long sentence.
@@ -125,17 +138,13 @@ To more accurately capture human expression, use an exclamation mark after just
-## Parentheses
-Use **parentheses** to offer more context to a term or phrase (such as a description or short example).
-
-Do not use parentheses to indicate a possible plural of something, like "account(s)." When a user can either select one thing or multiple things, use the plural form.
+### Parentheses ( )
+**Parentheses** are used to offer more context to a term or phrase.
-## Quotation marks
-Use double **quotation marks** (“Example”) for quotes and article titles. Use single quotation marks (‘Example’) for quotes or article titles within double quotation marks.
-
-While double quotation marks are the standard in American English, single quotation marks are usually the standard in British English.
+
-Double quotation marks and single quotation marks are sometimes used interchangeably across various publications. In some contexts, they can mean the same thing, but they are not always interchangeable. For instance, when you need to use nested quotation marks, single quotation marks should be used inside of double quotation marks. For example:
+| **Don't** | **Do** |
+|------------|-----------|
+| Do not use parentheses to indicate a possible plural of something, like "account(s)." When a user can either select one thing or multiple things, use the plural form. | Use parentheses to offer a description or short example.|
-- An article title within a dialogue: *Abi said, “I love the article Cat wrote. It’s called ‘Improving product design with an open source mindset,’ and it’s such a fun read.”*
-- A quote within a dialogue: *“I like Cat’s article too, Abi. My coworker told me, ‘PatternFly has the best publication ever.’ That made me smile.”*
\ No newline at end of file
+
\ No newline at end of file
diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/content/terminology.md b/packages/documentation-site/patternfly-docs/content/design-guidelines/content/terminology.md
index b10413306b..e8b77ea5e7 100644
--- a/packages/documentation-site/patternfly-docs/content/design-guidelines/content/terminology.md
+++ b/packages/documentation-site/patternfly-docs/content/design-guidelines/content/terminology.md
@@ -29,7 +29,6 @@ For Red Hat product terminology and documentation standards, see [Red Hat's supp
| **Edit** (v.) | Use to describe making changes to an object (like a file, configuration, or policy). | | *Modify* and *Change* are not recommended for this use case.|
| **Expand** (v.) | Use to describe expanding a container element (like a list or message) to show all its contents. | *Collapse*
| **Export** (v.) | Use to describe packing the contents (like a project or spreadsheet) from a website or application to a file format (like .pdf or .xslx) to your system. | *Import* | Do not use interchangeably with *Download*.
-| **Export** (v.) | Use to describe packing the contents (like a project or spreadsheet) from a website or application to a file format (like .pdf or .xslx) to your system. | *Import* | Do not use interchangeably with *Download*.
| **Filter** (v.) | Use to describe the action of narrowing a set of search results to show only items meeting a certain criteria. Filtering is mostly associated with views like tables, lists, and card grids and assumes that a search has previously been performed to return an initial results list.
| **Hide** (v.) | Use to describe hiding something that is displayed in the interface. | *Show*
| **Home page** (n.) | Use to describe the main page of a website. | | Write *Home page* as two words, not one.
diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/content/units-and-symbols.md b/packages/documentation-site/patternfly-docs/content/design-guidelines/content/units-and-symbols.md
index 086072b9b4..94541723e9 100644
--- a/packages/documentation-site/patternfly-docs/content/design-guidelines/content/units-and-symbols.md
+++ b/packages/documentation-site/patternfly-docs/content/design-guidelines/content/units-and-symbols.md
@@ -99,7 +99,7 @@ If space is limited, use symbols to communicate the same units of time in less s
| Millisecond | ms
| Second | s
| Minute | min
-| Hour | hr
+| Hour | h
diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/content/writing-for-all-audiences.md b/packages/documentation-site/patternfly-docs/content/design-guidelines/content/writing-for-all-audiences.md
index 33eb635ffc..317868116d 100644
--- a/packages/documentation-site/patternfly-docs/content/design-guidelines/content/writing-for-all-audiences.md
+++ b/packages/documentation-site/patternfly-docs/content/design-guidelines/content/writing-for-all-audiences.md
@@ -5,6 +5,8 @@ section: UX writing
By following accessibility and global writing best practices, you’ll be better equipped to create product experiences for users of all abilities and backgrounds.
+In addition to this page, you can also reference [this Red Hat documentation guide for accessible writing](https://redhat-documentation.github.io/accessibility-guide/).
+
## Writing for all abilities
When designing interfaces, consider all users’ abilities, including physical and cognitive. Use words that are clear, concise, and consistent. Refer to the [Web Content Accessibility Guidelines (WCAG)](https://www.w3.org/TR/WCAG21/) for accessibility compliance information.