diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/content/error-messages.md b/packages/documentation-site/patternfly-docs/content/design-guidelines/content/error-messages.md index 05155e439a..39c93d622c 100644 --- a/packages/documentation-site/patternfly-docs/content/design-guidelines/content/error-messages.md +++ b/packages/documentation-site/patternfly-docs/content/design-guidelines/content/error-messages.md @@ -91,7 +91,7 @@ However, don’t include too much information. The user doesn’t need to know e
-#### **Lead with the benefit**. +#### Lead with the benefit When providing users with a resolution, start the sentence with their goal ("the benefit"), followed by what they need to do to continue. diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/content/img/elements-guidelines.png b/packages/documentation-site/patternfly-docs/content/design-guidelines/content/img/elements-guidelines.png new file mode 100644 index 0000000000..87c940c10f Binary files /dev/null and b/packages/documentation-site/patternfly-docs/content/design-guidelines/content/img/elements-guidelines.png differ 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 3b303c8277..d099d7b331 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,6 +3,20 @@ id: Punctuation section: UX writing --- +## Headings and titles +Headings and titles can include punctuation, but should not end in punctuation. For example: + +
+ +|**Before** | **After** | +|------------|-----------| +| Style, voice, and tone. | Style, voice, and tone | +| Getting started with PatternFly! | Getting started with PatternFly | + +
+ +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?". + ## 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: 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 4d6dec6516..bec46d5886 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 @@ -76,7 +76,7 @@ Use abbreviations that users are familiar with, and write out uncommon abbreviat | **U.S.** | As a noun, use *United States* unless there are space constraints. As an adjective, use *U.S.* (for example, *U.S. soldier*). As part of an organization, use *U.S.*

Taken from Red Hat Corporate Style Guide. | | **URL** | Stands for *Uniform Resource Locator*. Write *URL* in all caps. | | **VM** | Refers to a virtual machine. OK to abbreviate as long as you've spelled it out once in the first occurrence and as long as *VM* won't be confused with other terms that share that acronym.

Taken from Red Hat Corporate Style Guide. | -| ** N/A ** | Refers to *data not applicable*, meaning data will never apply to the object and will never populate. | -| **--** | Refers to *data not available*, meaning data could apply to the object, but is currently not populating. | +| **N/A** | Refers to *data not applicable*, meaning data does not currently apply to the object and will not populate.

This includes scenarios where there is no matching data in the object's data source. For example, when nothing matches a filter, when the data source is empty, or when the object is not connected to any data source.| +| **--** | Refers to *data not available*, meaning data could apply to the object, but is currently not populating.

This includes scenarios where the object is connected to a data source, but is not able to fetch data. For example, when there are permission restrictions or errors.| \ No newline at end of file diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/content/writing-patternfly-design-guidelines.md b/packages/documentation-site/patternfly-docs/content/design-guidelines/content/writing-patternfly-design-guidelines.md index ed79775f12..d69ce2d3e8 100644 --- a/packages/documentation-site/patternfly-docs/content/design-guidelines/content/writing-patternfly-design-guidelines.md +++ b/packages/documentation-site/patternfly-docs/content/design-guidelines/content/writing-patternfly-design-guidelines.md @@ -11,11 +11,9 @@ To learn how to contribute design guidelines, see our [contribution guide](https When creating guidelines, information must be presented in the following order. Sections may be omitted, but if present must use the following section headings (H2). ### Elements -Display an image of the component containing numbered annotation tags for each major part of the component's visual design. Include specific icons, headers, fields, symbols, and anything else included in the component's structure. Following the image, list all the parts you tagged, aligning with the number displayed in the respective annotation tag. In this list, provide a description of each one. +Display an image of the component containing numbered annotation tags for each major part of the component's visual design. Include specific icons, headers, fields, symbols, and anything else included in the component's structure. Following the image, list all the parts you tagged, aligning with the number displayed in the respective annotation tag. In this list, provide a description of each one. For example: -Example: - -A screenshot of the slider component's element section with 8 elements outlined. +A screenshot of the slider component's element section with 8 elements outlined. ### Usage Explain how the component is used, when to use it, and why it should be used. Include explanations of problems it could help solve and address its advantages over similar components. Include images for visual examples.