Skip to content

Commit

Permalink
fix: hyphens to en dashes (#3215)
Browse files Browse the repository at this point in the history
* chore: untrack git file

- fix vscode settings which shouldn't have been tracked

* docs: replace hyphens with en dashes
  • Loading branch information
mattrosno committed Oct 25, 2022
1 parent dffcd64 commit fb72b82
Show file tree
Hide file tree
Showing 2 changed files with 18 additions and 25 deletions.
7 changes: 0 additions & 7 deletions .vscode/settings.json

This file was deleted.

36 changes: 18 additions & 18 deletions src/pages/guidelines/content/writing-style.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -3,15 +3,15 @@ title: Content
description:
Writing should always be simple, clear, and easy to understand. Using everyday
language keeps the tone friendly, human, and inviting. And choose short words
over long impressive-sounding words. Put the thesaurus away!
over long, impressivesounding words. Put the thesaurus away!
tabs: ['Overview', 'Writing style', 'Action labels']
---

<PageDescription>

Writing should always be simple, clear, and easy to understand. Using everyday
language keeps the tone friendly, human, and inviting. And choose short words
over long impressive-sounding words. Put the thesaurus away!
over long, impressivesounding words. Put the thesaurus away!

</PageDescription>

Expand All @@ -28,9 +28,9 @@ over long impressive-sounding words. Put the thesaurus away!

## Capitalization

### Use sentence-case capitalization
### Use sentencecase capitalization

Use sentence-case capitalization for all UI text elements. This style is
Use sentencecase capitalization for all UI text elements. This style is
predominantly lowercase. Capitalize only the initial letter of the first word in
the text and other words that require capitalization, such as proper nouns. For
example, labels in a form would be written as “First name” and “Email address”.
Expand All @@ -43,27 +43,27 @@ text, table headers, and table content all following the sentence case rule.

![Sentence case for UI elements](/images/sentence_case_786.png)

<Caption>Example of a product page using sentence-style capitalization</Caption>
<Caption>Example of a product page using sentencestyle capitalization</Caption>

</Column>
</Row>

Sentence-style capitalization makes it easy for readers to distinguish between
Sentencestyle capitalization makes it easy for readers to distinguish between
common nouns and proper nouns, and is generally considered the quickest form to
read.

> Do not capitalize the names of features and components unless they are sold
> separately or are trademarked.
>
> <cite>- The IBM Style Guide: Conventions for Writers and Editors</cite>
> <cite> The IBM Style Guide: Conventions for Writers and Editors</cite>
Carbon does not consider UI elements within a product to be proper nouns. Nor
does Carbon support a concept of “important words” or “specialness”. Determining
whether something is important or special is highly subjective and can result in
inconsistencies across an organization.

Unless the name is a product or service name, or is trademarked, always use
sentence-style capitalization.
sentencestyle capitalization.

In the following examples, the capitalization shows that Padlock, Visual
Recognition, and IBM Cloud are either products or services.
Expand Down Expand Up @@ -145,7 +145,7 @@ Capital letters are reserved for the following:
- “Carbon” or the “Carbon Design System” (the name of IBM’s official design
system)
- “IBM” or any other company or organization name
- Any official, trademarked product or service (whether from IBM or not) -
- Any official, trademarked product or service (whether from IBM or not)
unless they intentionally use a lowercase letter at the beginning, such as the
iPhone
- Any initialisms (for example, BBC, HTML) or acronyms (for example, NASA, NATO)
Expand All @@ -156,7 +156,7 @@ Capital letters are reserved for the following:

If it’s not in the list above, it should not be capitalized.

Sometimes official company and product names use non-standard capitalization. If
Sometimes official company and product names use nonstandard capitalization. If
you refer to any of these, ensure you write them accurately. Here are some
examples (all written correctly):

Expand All @@ -170,8 +170,8 @@ examples (all written correctly):

When writing about a UI element, use the same capitalization as used in the UI.
For example, if an input field is labeled “Name” then you refer to this as the
Name input field. Similarly, if a drop-down menu has the label “Country” next to
it, then it is correct to refer to the Country drop-down menu. Where a product
Name input field. Similarly, if a dropdown menu has the label “Country” next to
it, then it is correct to refer to the Country dropdown menu. Where a product
page is titled “My network”, you refer to this in writing as follows: “Enter
your network information in the My network page”.

Expand Down Expand Up @@ -225,7 +225,7 @@ been specifically approved, as with IBM CICS.
<DoDont type="dont" text="Experience WAS on IBM Cloud..." aspectRatio="1:1" />
</DoDontRow>

Use all uppercase letters for well-recognized abbreviations. This applies to
Use all uppercase letters for wellrecognized abbreviations. This applies to
both initialisms, such as IBM, and to acronyms, such as GIF.

- ASCII
Expand Down Expand Up @@ -295,7 +295,7 @@ has, had, been, should, would, and will.

To set the appropriate tone and conversation level, it helps to imagine the user
engaging with the product as if in a conversation. The interplay between words,
imagery, and interactions forms the conversation, a back-and-forth that takes
imagery, and interactions forms the conversation, a backandforth that takes
place on the glass, between the user and the product.

The conversational level is determined by where the user is in the journey, and
Expand All @@ -307,7 +307,7 @@ of words is desirable.
Whatever the conversational level, the writing should always be simple, clear,
and easy to understand. And keep the tone friendly, human, and inviting. Use
everyday language, not jargon. And choose short words to make the reading
faster, rather than long impressive-sounding words. Put the thesaurus away!
faster, rather than long, impressivesounding words. Put the thesaurus away!

IBM Style offers more guidelines on
[conversational style](<[https://www-03preprod.ibm.com/support/knowledgecenter/ibm_style/conversational-style.html](https://ibmdocs-test.mybluemix.net/docs/en/ibm-style?topic=medium-conversational-style)>).
Expand Down Expand Up @@ -410,10 +410,10 @@ offerings be inclusive in their language.

IBMers who are unsure about a particular word can search the
[IBM Terminology database](http://ibm.biz/termsearch), and can
also [submit a term for review](http://tlwi.w3-969.ibm.com/standards/terminology/feedbackform2.html).
also [submit a term for review](http://tlwi.w3-969.ibm.com/standards/terminology/feedbackform2.html).

For more information about this important work, see
the [Inclusive IT Terminology](https://w3.ibm.com/w3publisher/inclusive-it-terminology/take-action) site.
the [Inclusive IT Terminology](https://w3.ibm.com/w3publisher/inclusive-it-terminology/take-action) site.

## Pronouns

Expand Down Expand Up @@ -441,7 +441,7 @@ requests for personal information, such as name and email address, where the
user will benefit from knowing why IBM is asking for this information. Example:
“Why do we need your email address?”

Avoid third-person pronouns that are gender specific.
Avoid thirdperson pronouns that are gender specific.

For more detailed guidance about pronouns, refer to the
[Pronouns](https://ibmdocs-test.mybluemix.net/docs/en/ibm-style?topic=grammar-pronouns)
Expand Down

1 comment on commit fb72b82

@vercel
Copy link

@vercel vercel bot commented on fb72b82 Oct 25, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please sign in to comment.