Skip to content

Commit

Permalink
Docs--update-content-guidance (#1739)
Browse files Browse the repository at this point in the history
  • Loading branch information
@oliviaflory
oliviaflory authored Dec 7, 2023
1 parent 5a97b12 commit b8e4a42
Showing 1 changed file with 22 additions and 31 deletions.
53 changes: 22 additions & 31 deletions src/pages/guidelines/content.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,6 @@ Well-designed content empowers people to use our offerings with ease. These guid
<AnchorLink>Character count standards</AnchorLink>
<AnchorLink>Inclusive language</AnchorLink>
<AnchorLink>Writing for accessibility</AnchorLink>
<AnchorLink>Additional resources</AnchorLink>

</AnchorLinks>

Expand All @@ -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:

- <a
href="https://ibmdocs-test.mybluemix.net/docs/en/ibm-style"
target="_blank"
>
The IBM Style Guide
</a>
- <a
href="https://www.carbondesignsystem.com/guidelines/content/overview"
target="_blank"
>
The Carbon Design System for content
</a>
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

Expand Down Expand Up @@ -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 <a href="https://ibmdocs-test.dcs.ibm.com/docs/en/ibm-style?topic=grammar-capitalization" target="_blank">Capitalization</a> topic in IBM Style.

## Pronouns

In general, use the second person (you, your) as often as possible.
Expand All @@ -139,7 +142,7 @@ For more detailed guidance about pronouns, refer to the <a href="https://ibmdocs

The following character count sizes should be used for all components and patterns when setting text content.

| Name | Size (English) | Size (translated) |
| Name (size) | Character count (English) | Character count (translated) |
| :---- | :------------- | :---------------- |
| Micro | 20 | 32 |
| Mini | 25 | 35 |
Expand All @@ -155,7 +158,7 @@ The following character count sizes should be used for all components and patter
### Translation conversion table

The following table provides a good indication of the amount of additional space needed to contain a text passage after
translation. This is the official statement about string length calculation for translations, according to Rule A3 in <a target="_blank" href="http://w3-03.ibm.com/globalization/page/4619">IBM Globalization Design Guide</a>.
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,
Expand All @@ -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 <a href="http://ibm.biz/termsearch" target="_blank" rel="noopener noreferrer">IBM Terminology database</a>, and can also <a href="http://tlwi.w3-969.ibm.com/standards/terminology/feedbackform2.html" target="_blank" rel="noopener noreferrer">submit a term for review</a>.
IBMers who are unsure about a particular word can search the <a href="http://ibm.biz/termsearch" target="_blank" rel="noopener noreferrer">IBM Terminology database</a>, and can also <a href="https://w3.terminology.g11n.ibm.com/standards/terminology/feedback/review" target="_blank" rel="noopener noreferrer">submit a term for review</a>.

For more information about this important work, see the <a href="https://w3.ibm.com/w3publisher/inclusive-it-terminology/take-action" target="_blank" rel="noopener noreferrer">Inclusive IT Terminology</a> 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:
Expand All @@ -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. |

0 comments on commit b8e4a42

Please sign in to comment.