{"componentChunkName":"component---src-pages-guidelines-content-guidance-mdx","path":"/guidelines/content/guidance/","result":{"pageContext":{"frontmatter":{"title":"Content","description":"Inconsistencies in grammar and style interrupt concentration. Help users focus on your product by following these guidelines and applying them consistently.","tabs":["General","Guidance","Action labels"]},"relativePagePath":"/guidelines/content/guidance.mdx","titleType":"prepend","MdxNode":{"id":"4a1410ec-e189-5fea-b1d2-670f9148db17","children":[],"parent":"15a41cb0-ff7c-5625-9b6e-78a185b677fa","internal":{"content":"---\ntitle: Content\ndescription: Inconsistencies in grammar and style interrupt concentration. Help users focus on your product by following these guidelines and applying them consistently.\ntabs: ['General', 'Guidance', 'Action labels']\n---\n\n\n\nInconsistencies in grammar and style interrupt concentration. Help users focus on your product by following these guidelines and applying them consistently.\n\n\n\n\n\nCapitalization\nVerb tense\nActive and passive voice\nFirst and second person\nFormal vs. casual tone\nCan, may, and might\nReferences\n\n\n\n## Capitalization\n\n### Use sentence-case capitalization\n\nUse sentence-case 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.”\n\nThe image below shows a page title, tabs, a module title, link text, button text, table headers, and table content all following the sentence case rule.\n\n\n\n\n\n\nExample of a product page using sentence-style capitalization\n\n\n
\n\nSentence-style capitalization makes it easy for readers to distinguish between common nouns and proper nouns, and is generally considered the quickest form to read.\n\n> Do not capitalize the names of features and components unless they are sold separately or are trademarked.\n>\n> - The IBM Style Guide: Conventions for Writers and Editors\n\nCarbon 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.\n\nUnless the name is a product or service name, or is trademarked, always use sentence-style capitalization.\n\nIn the following examples, the capitalization shows that Padlock, Visual Recognition, and IBM Cloud are either products or services.\n\n\n \n \n\n\n### Referring to UI elements\n\nWhen 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 page is titled “My network,” you refer to this in writing as follows: “Enter your network information in the My network page.”\n\n\n \n \n\n\n### When to use capital letters\n\nCapital letters are reserved for the following:\n\n- “Carbon” or the “Carbon Design System” (i.e. the name of IBM’s official design system)\n- “IBM” or any other company or organization name\n- 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\n- Any initialisms (e.g. BBC, HTML, etc.) or acronyms (e.g. NASA, NATO, etc.)\n- Any people\n- Any country / place names\n- When referring to any UI labels that are themselves capitalized\n- When the word begins a sentence or phrase\n\nIf it’s not in the list above, it should not be capitalized.\n\nSometimes official company and product names use non-standard capitalization. If you refer to any of these, ensure you write them accurately. Here are some examples (all written correctly):\n\n- developerWorks\n- GitHub\n- iTunes\n- JavaScript\n- WebSphere\n\n### Do not use title case capitalization\n\n**Title (or headline) case capitalization** is where the first letter of most words is capitalized, but not articles, conjunctions, or prepositions (except if any of these are the first or last word in the sentence or phrase).\n\nTitle case is difficult to implement consistently across an organization because:\n\n1. It requires everyone who writes any copy to understand and follow fairly complex grammatical rules about which words should and shouldn't be capitalized, and\n\n1. It relies on a subjective viewpoint of what is considered “important” or “special” and that viewpoint being communicated or understood somehow.\n\nTitle case can also slow reading and comprehension down as it is more difficult for readers to distinguish between proper nouns and common nouns.\n\n\n \n \n\n\n### Do not use all caps capitalization\n\n**All caps (or uppercase) capitalization** is where every letter is capitalized.\n\nAll caps capitalization has been shown to be slower to read (especially when text is more than a few words) as individual letter shapes are less distinguishable from each other—they are the same height and have no ascenders or descenders. This style also typically requires more space in the UI per letter than sentence case does.\n\nIn addition, it can be difficult for the reader to distinguish between proper nouns and common nouns. In the first example below, it's easy to distinguish product names from features whereas it takes longer to make these distinctions when the text is in all caps.\n\n\n \n \n\n\n### Capitalizing proper nouns\n\nThe names of people, places, and products are proper nouns and therefore all take initial capitals. Examples of proper nouns are:\n\n- Eliot Noyes\n- IBM Watson Studio\n- Paris, France\n- Porsche Boxster\n\nThere are many words that can act as either a common noun or a proper noun, depending on the context. So, you always need to think about how the word is being used. Here are some examples:\n\n| Word | Used as a common noun | Used as a proper noun |\n| ------------------- | ------------------------------------------------ | -------------------------------------------------- |\n| agile | The group uses agile tools and processes | Debs referred her manager to the Agile Manifesto |\n| design | Jodi works in the design organization | Jodi works for IBM Design |\n| editor | Joe used a text editor to update the config file | Joe used IBM Flow Editor to define his data models |\n| front end developer | Jane is hoping to recruit a front end developer | Megan’s job title is Senior Front End Developer |\n\n### Capitalizing abbreviations\n\n**IBM product and service names**\n\nWhen referencing the name of any IBM product, use the official (full) name, not an abbreviation or just the product name initials, unless a shortened name has been specifically approved, as with IBM CICS.\n\n\n \n \n\n\nUse all uppercase letters for well-recognized abbreviations. This applies to both initialisms, such as IBM, and to acronyms, such as GIF.\n\n- ASCII\n- CAPTCHA\n- FAQ\n- HTML\n- OK (not Ok or Okay)\n- WDSL\n\nIf there's a chance that an abbreviation might not be known to the target audience, it's good practice to spell it out in full the first time you use it. However, don't spell out commonly known abbreviations, for example PDF, CEO, AM/PM.\n\n### Capitalizing all other words\n\nUnless the word begins a sentence, phrase, or UI element name, don't give it a capital letter.\n\nDon't give a word a capital letter to denote “specialness.” If you want to emphasize a particular word or phrase within a sentence, use italic or bold formatting (but not both).\n\n\n \n \n\n\n## Active and passive voice\n\nThe _active voice_ is direct and punchy, and emphasizes the subject of the sentence. The subject clearly “acts upon” the verb (hence, “active”). For example, “John ate the apple.” In situations where either voice will work, generally choose the active voice for more directness.\n\n\n \n \n\n\nThe _passive voice_, on the other hand, flips the construction so that the subject is secondary to the verb and object (hence, “passive”). Often, the subject is not even included in the sentence. For example, “_The apple was eaten by John_” or just “_The apple was eaten_.” Only sentences that contain direct objects can be constructed in the passive voice. Thus, “_John ate_” cannot be constructed passively.\n\nThe passive voice makes for a more natural tone in certain use cases. For example, if the true subject of the sentence is a system, and the human is secondary, passive voice can be acceptable.\n\n\n \n \n\n\n## First and second person\n\nEngage your readers by using second person **(you, your)** where appropriate. First person **(I, we, our)** focuses on the writer rather than the audience, which is rarely appropriate in UI or technical contexts. Avoid the first person unless you have a compelling reason to use it.\n\nOne exception to this is in the case of possessive adjectives in the UI. You can use first person in headings or labels that are very specific to the user or customer data, such as “My Account” or “My Usage.” In explanatory text for the heading or label, however, use second person. For example, _“Your usage is calculated from the first day of the month.”_\n\n## Formal vs. casual tone\n\nWhile a more formal tone is often appropriate for technical and business writing, a more casual tone is becoming increasingly accepted (and expected) in UI and supporting materials.\n\n- Don't be afraid to use **contractions**. When they fit the context and improve flow, go for it.\n- Beginning sentences with **and, but, or so** is not always forbidden. When it allows for shorter, scannable sentences, they can be used. Do not overuse these devices, especially in instructional content. For example, _“You can deploy an app to the cloud during lunch hour. But it's not required.”_ works for _Discover, Try, Buy_ experiences.\n- It's acceptable to use **questions in headings**. In both UIs and documentation, questions can be used to further conversational style. But don't overuse them, as they can add to noise. Make sure headings that use questions are meaningful. In a UI, questions can also be used in a confirmation prompt in a dialog box. For example, _“Do you want to close without saving?”_\n- Use **exclamation marks** only positively, not negatively. Make sure you use no more than one exclamation mark in a context, such as a single window or a single Docs topic.\n\n\n \n \n\n\n#### Terms of politeness\n\nOften overused, these terms can convey the wrong tone for technical material, and are not regarded the same way in all cultures. Use terms such as “please” and “thank you” carefully.\n\n\n \n \n\n\n## Can, may, and might\n\n#### Terms of ability\n\nThese terms are often misused. Remember, “can” implies ability, and “may” implies permission (and sometimes uncertainty).\n\n\n \n \n\n\n#### Terms of possibility\n\nThese terms can also be confusing. Remember, when either “may” or “might” will work, generally go with “might” to avoid confusion with the multiple meanings of “may.”\n\n\n \n \n\n\n## References\n\nEric Radzinski, Leslie McDonald, Amy Laird, Jana Jenkins, Peter Hayward, and Francis DeRespinis, [The IBM Style Guide: Conventions for Writers and Editors](https://learning.oreilly.com/library/view/the-ibm-style/9780132118989/), (IBM Press, 2011)\n\nTom Waterton, [How to emphasize key words in your text](https://medium.com/@tomwaterton/how-to-emphasize-key-words-in-your-text-b8738f146972), (Medium, 2017)\n","type":"Mdx","contentDigest":"6051b1cd134da4bf030b07a200dd017b","counter":1659,"owner":"gatsby-plugin-mdx"},"frontmatter":{"title":"Content","description":"Inconsistencies in grammar and style interrupt concentration. Help users focus on your product by following these guidelines and applying them consistently.","tabs":["General","Guidance","Action labels"]},"exports":{},"rawBody":"---\ntitle: Content\ndescription: Inconsistencies in grammar and style interrupt concentration. Help users focus on your product by following these guidelines and applying them consistently.\ntabs: ['General', 'Guidance', 'Action labels']\n---\n\n\n\nInconsistencies in grammar and style interrupt concentration. Help users focus on your product by following these guidelines and applying them consistently.\n\n\n\n\n\nCapitalization\nVerb tense\nActive and passive voice\nFirst and second person\nFormal vs. casual tone\nCan, may, and might\nReferences\n\n\n\n## Capitalization\n\n### Use sentence-case capitalization\n\nUse sentence-case 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.”\n\nThe image below shows a page title, tabs, a module title, link text, button text, table headers, and table content all following the sentence case rule.\n\n\n\n\n\n\nExample of a product page using sentence-style capitalization\n\n\n
\n\nSentence-style capitalization makes it easy for readers to distinguish between common nouns and proper nouns, and is generally considered the quickest form to read.\n\n> Do not capitalize the names of features and components unless they are sold separately or are trademarked.\n>\n> - The IBM Style Guide: Conventions for Writers and Editors\n\nCarbon 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.\n\nUnless the name is a product or service name, or is trademarked, always use sentence-style capitalization.\n\nIn the following examples, the capitalization shows that Padlock, Visual Recognition, and IBM Cloud are either products or services.\n\n\n \n \n\n\n### Referring to UI elements\n\nWhen 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 page is titled “My network,” you refer to this in writing as follows: “Enter your network information in the My network page.”\n\n\n \n \n\n\n### When to use capital letters\n\nCapital letters are reserved for the following:\n\n- “Carbon” or the “Carbon Design System” (i.e. the name of IBM’s official design system)\n- “IBM” or any other company or organization name\n- 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\n- Any initialisms (e.g. BBC, HTML, etc.) or acronyms (e.g. NASA, NATO, etc.)\n- Any people\n- Any country / place names\n- When referring to any UI labels that are themselves capitalized\n- When the word begins a sentence or phrase\n\nIf it’s not in the list above, it should not be capitalized.\n\nSometimes official company and product names use non-standard capitalization. If you refer to any of these, ensure you write them accurately. Here are some examples (all written correctly):\n\n- developerWorks\n- GitHub\n- iTunes\n- JavaScript\n- WebSphere\n\n### Do not use title case capitalization\n\n**Title (or headline) case capitalization** is where the first letter of most words is capitalized, but not articles, conjunctions, or prepositions (except if any of these are the first or last word in the sentence or phrase).\n\nTitle case is difficult to implement consistently across an organization because:\n\n1. It requires everyone who writes any copy to understand and follow fairly complex grammatical rules about which words should and shouldn't be capitalized, and\n\n1. It relies on a subjective viewpoint of what is considered “important” or “special” and that viewpoint being communicated or understood somehow.\n\nTitle case can also slow reading and comprehension down as it is more difficult for readers to distinguish between proper nouns and common nouns.\n\n\n \n \n\n\n### Do not use all caps capitalization\n\n**All caps (or uppercase) capitalization** is where every letter is capitalized.\n\nAll caps capitalization has been shown to be slower to read (especially when text is more than a few words) as individual letter shapes are less distinguishable from each other—they are the same height and have no ascenders or descenders. This style also typically requires more space in the UI per letter than sentence case does.\n\nIn addition, it can be difficult for the reader to distinguish between proper nouns and common nouns. In the first example below, it's easy to distinguish product names from features whereas it takes longer to make these distinctions when the text is in all caps.\n\n\n \n \n\n\n### Capitalizing proper nouns\n\nThe names of people, places, and products are proper nouns and therefore all take initial capitals. Examples of proper nouns are:\n\n- Eliot Noyes\n- IBM Watson Studio\n- Paris, France\n- Porsche Boxster\n\nThere are many words that can act as either a common noun or a proper noun, depending on the context. So, you always need to think about how the word is being used. Here are some examples:\n\n| Word | Used as a common noun | Used as a proper noun |\n| ------------------- | ------------------------------------------------ | -------------------------------------------------- |\n| agile | The group uses agile tools and processes | Debs referred her manager to the Agile Manifesto |\n| design | Jodi works in the design organization | Jodi works for IBM Design |\n| editor | Joe used a text editor to update the config file | Joe used IBM Flow Editor to define his data models |\n| front end developer | Jane is hoping to recruit a front end developer | Megan’s job title is Senior Front End Developer |\n\n### Capitalizing abbreviations\n\n**IBM product and service names**\n\nWhen referencing the name of any IBM product, use the official (full) name, not an abbreviation or just the product name initials, unless a shortened name has been specifically approved, as with IBM CICS.\n\n\n \n \n\n\nUse all uppercase letters for well-recognized abbreviations. This applies to both initialisms, such as IBM, and to acronyms, such as GIF.\n\n- ASCII\n- CAPTCHA\n- FAQ\n- HTML\n- OK (not Ok or Okay)\n- WDSL\n\nIf there's a chance that an abbreviation might not be known to the target audience, it's good practice to spell it out in full the first time you use it. However, don't spell out commonly known abbreviations, for example PDF, CEO, AM/PM.\n\n### Capitalizing all other words\n\nUnless the word begins a sentence, phrase, or UI element name, don't give it a capital letter.\n\nDon't give a word a capital letter to denote “specialness.” If you want to emphasize a particular word or phrase within a sentence, use italic or bold formatting (but not both).\n\n\n \n \n\n\n## Active and passive voice\n\nThe _active voice_ is direct and punchy, and emphasizes the subject of the sentence. The subject clearly “acts upon” the verb (hence, “active”). For example, “John ate the apple.” In situations where either voice will work, generally choose the active voice for more directness.\n\n\n \n \n\n\nThe _passive voice_, on the other hand, flips the construction so that the subject is secondary to the verb and object (hence, “passive”). Often, the subject is not even included in the sentence. For example, “_The apple was eaten by John_” or just “_The apple was eaten_.” Only sentences that contain direct objects can be constructed in the passive voice. Thus, “_John ate_” cannot be constructed passively.\n\nThe passive voice makes for a more natural tone in certain use cases. For example, if the true subject of the sentence is a system, and the human is secondary, passive voice can be acceptable.\n\n\n \n \n\n\n## First and second person\n\nEngage your readers by using second person **(you, your)** where appropriate. First person **(I, we, our)** focuses on the writer rather than the audience, which is rarely appropriate in UI or technical contexts. Avoid the first person unless you have a compelling reason to use it.\n\nOne exception to this is in the case of possessive adjectives in the UI. You can use first person in headings or labels that are very specific to the user or customer data, such as “My Account” or “My Usage.” In explanatory text for the heading or label, however, use second person. For example, _“Your usage is calculated from the first day of the month.”_\n\n## Formal vs. casual tone\n\nWhile a more formal tone is often appropriate for technical and business writing, a more casual tone is becoming increasingly accepted (and expected) in UI and supporting materials.\n\n- Don't be afraid to use **contractions**. When they fit the context and improve flow, go for it.\n- Beginning sentences with **and, but, or so** is not always forbidden. When it allows for shorter, scannable sentences, they can be used. Do not overuse these devices, especially in instructional content. For example, _“You can deploy an app to the cloud during lunch hour. But it's not required.”_ works for _Discover, Try, Buy_ experiences.\n- It's acceptable to use **questions in headings**. In both UIs and documentation, questions can be used to further conversational style. But don't overuse them, as they can add to noise. Make sure headings that use questions are meaningful. In a UI, questions can also be used in a confirmation prompt in a dialog box. For example, _“Do you want to close without saving?”_\n- Use **exclamation marks** only positively, not negatively. Make sure you use no more than one exclamation mark in a context, such as a single window or a single Docs topic.\n\n\n \n \n\n\n#### Terms of politeness\n\nOften overused, these terms can convey the wrong tone for technical material, and are not regarded the same way in all cultures. Use terms such as “please” and “thank you” carefully.\n\n\n \n \n\n\n## Can, may, and might\n\n#### Terms of ability\n\nThese terms are often misused. Remember, “can” implies ability, and “may” implies permission (and sometimes uncertainty).\n\n\n \n \n\n\n#### Terms of possibility\n\nThese terms can also be confusing. Remember, when either “may” or “might” will work, generally go with “might” to avoid confusion with the multiple meanings of “may.”\n\n\n \n \n\n\n## References\n\nEric Radzinski, Leslie McDonald, Amy Laird, Jana Jenkins, Peter Hayward, and Francis DeRespinis, [The IBM Style Guide: Conventions for Writers and Editors](https://learning.oreilly.com/library/view/the-ibm-style/9780132118989/), (IBM Press, 2011)\n\nTom Waterton, [How to emphasize key words in your text](https://medium.com/@tomwaterton/how-to-emphasize-key-words-in-your-text-b8738f146972), (Medium, 2017)\n","fileAbsolutePath":"/zeit/3f757860/src/pages/guidelines/content/guidance.mdx"}}}}