From 8886d9a211865afbf9fcf2af7af955cf8e79bf8d Mon Sep 17 00:00:00 2001 From: Olivia Flory <45692622+oliviaflory@users.noreply.github.com> Date: Wed, 6 Dec 2023 15:31:14 -0500 Subject: [PATCH] Docs--update-content-guidance --- src/pages/guidelines/content.mdx | 53 +++++++++++++------------------- 1 file changed, 22 insertions(+), 31 deletions(-) diff --git a/src/pages/guidelines/content.mdx b/src/pages/guidelines/content.mdx index 597768ae5..4943c2a09 100644 --- a/src/pages/guidelines/content.mdx +++ b/src/pages/guidelines/content.mdx @@ -18,7 +18,6 @@ Well-designed content empowers people to use our offerings with ease. These guid Character count standards Inclusive language Writing for accessibility -Additional resources @@ -34,20 +33,22 @@ The following are guidelines on how to create effective content. For starters, h - In general, use a complete sentence to introduce a list. Introduce procedures with a sentence, an infinitive phrase, or a heading. -While you’ll find the most common content guidelines here, refer to these two sources for more in-depth information: - -- - The IBM Style Guide - -- - The Carbon Design System for content - +Familiarity with key IBM guidance is essential to creating experiences that are +consistent, that provide an interoperability of experience with other offerings, +and that represent IBM as a company. + +The Carbon content guidelines are built upon and informed by the following +foundational IBM assets. + +_Some of this content is accessible to IBMers only._ + +| Resources | What you'll find | +| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| _[IBM Style](http://ibm.biz/ibm-style-guide)_ | IBM Style is the corporate reference for all IBM writers and editors and applies to all content published by IBM. Its purpose is to ensure that content for external audiences is grammatically correct, clear, consistent, appropriate for global audiences, and easy to translate. | +| _[IBM Design Language](https://www.ibm.com/design/language/)_ | The IBM Design Language provides the guidance and assets used to express the IBM brand. You'll fully understand what drives IBM’s design philosophy and principles, and be in a position to make informed choices for your product work. | +| _[IBM Brand Center](https://www.ibm.com/brand/definition)_ | IBM Brand Center is the home base for the IBM Brand story, visual brand elements, guidelines, and assets. | +| _[IBM Brand Systems](https://www.ibm.com/brand/systems/)_ | The IBM brand systems have been developed for various IBM businesses, audiences, categories, and offerings. Read them to understand the rationale behind every visual and verbal detail. | + ## Voice and tone @@ -117,6 +118,8 @@ in the sentence or phrase). Instead, use sentence-case capitalization. If it’s not in the list above, it should not be capitalized. Capitalize proper nouns, such as the names of people, places, and products are proper nouns and therefore all take initial capitals. +For more detailed guidance about capitalization, refer to the Capitalization topic in IBM Style. + ## Pronouns In general, use the second person (you, your) as often as possible. @@ -139,7 +142,7 @@ For more detailed guidance about pronouns, refer to the IBM Globalization Design Guide. +translation. The numbers represent statistical averages. In some situations they will be overly generous, while in others the translator will have difficulty fitting in all the translated words. Ideally the translator can use any amount of space, @@ -174,14 +177,14 @@ but use the following list as a rough guide to the space that should be left for IBM is committed to eliminating language that supports racial, cultural, or gender bias. It is critical that all words used in any capacity in product offerings be inclusive in their language. -IBMers who are unsure about a particular word can search the IBM Terminology database, and can also submit a term for review. +IBMers who are unsure about a particular word can search the IBM Terminology database, and can also submit a term for review. For more information about this important work, see the Inclusive IT Terminology site. ## Writing for accessibility For detailed guidance about writing for all users, please read the -[Content design section](https://www.ibm.com/able/toolkit/design/content/text-equivalents) +[Content design section](https://www.ibm.com/able/toolkit/design/content/) of the IBM Accessibility site. It provides detailed guidance on the following topics: @@ -193,15 +196,3 @@ It provides detailed guidance on the following topics: Further guidance can be found in the [Web Content Accessibility guidelines](https://www.w3.org/WAI/standards-guidelines/wcag/). - -## Additional resources - -_Some of this content is accessible to IBMers only._ - -| Resources | What you'll find | -| ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| _[IBM Style](http://ibm.biz/ibm-style-guide)_ | IBM Style is the corporate reference for all IBM writers and editors and applies to all content published by IBM. Its purpose is to ensure that content for external audiences is grammatically correct, clear, consistent, appropriate for global audiences, and easy to translate. | -| _[Carbon Design System Content Guidelines](https://www.carbondesignsystem.com/guidelines/content/overview/)_ | Carbon is IBM’s open source design system for products. These guidelines have been developed from real-life examples and are for everyone who is writing or reviewing copy in IBM product interfaces. | -| _[IBM Design Language](https://www.ibm.com/design/language/)_ | The IBM Design Language provides the guidance and assets used to express the IBM brand. You'll fully understand what drives IBM’s design philosophy and principles, and be in a position to make informed choices for your product work. | -| _[IBM Brand Center](https://www.ibm.com/brand/definition)_ | IBM Brand Center is the home base for the IBM Brand story, visual brand elements, guidelines, and assets. | -| _[IBM Experience Guides](https://www.ibm.com/brand/experience-guides/)_ | The IBM brand systems have been developed for various IBM businesses, audiences, categories, and offerings. Read them to understand the rationale behind every visual and verbal detail. |