{"componentChunkName":"component---src-pages-guidelines-content-guidance-mdx","path":"/guidelines/content/guidance/","webpackCompilationHash":"aaa6c4cbb44f8ca938e9","result":{"pageContext":{"isCreatedByStatefulCreatePages":true,"frontmatter":{"label":"Content design can make or break an online experience. Always strive for writing that is clear, concise, and on-brand.","title":"Content","description":"Content design can make or break an online experience. Always strive for writing that is clear, concise, and on-brand.","tabs":["General","Guidance","Glossary"]},"relativePagePath":"/guidelines/content/guidance.mdx","titleType":"prepend","MdxNode":{"id":"cb680868-b4cb-5458-8c1f-29105308dc8a","children":[],"parent":"0c81a93f-750c-52a2-be70-19e5efb8e60e","internal":{"content":"---\nlabel: Content design can make or break an online experience. Always strive for writing that is clear, concise, and on-brand.\ntitle: Content\ndescription: Content design can make or break an online experience. Always strive for writing that is clear, concise, and on-brand.\ntabs: ['General', 'Guidance', 'Glossary']\n---\n\n### Content design can make or break an online experience. Always strive for writing that is clear, concise, and on-brand\n\n\n\nCapitalization\nVerb tense\nActive and passive voice\nFirst and second person\nFormal vs. casual tone\nCan, may, and might\n\n\n\n## Capitalization\n\nUse sentence-style capitalization in text and for all text elements in the UI except for proper nouns. Sentence style capitalizes only the first word of each sentence.\n\n#### Examples:\n\n- Cloud Foundry apps\n- Business models\n- Creating Boolean expressions\n- Planning network architectures\n- Carbon Design System\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 \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 \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 \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 \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 \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 \n \n
\n","type":"Mdx","contentDigest":"85954ec85e1cbe68852f6531608e6be3","counter":1209,"owner":"gatsby-plugin-mdx"},"frontmatter":{"title":"Content","label":"Content design can make or break an online experience. Always strive for writing that is clear, concise, and on-brand.","description":"Content design can make or break an online experience. Always strive for writing that is clear, concise, and on-brand.","tabs":["General","Guidance","Glossary"]},"exports":{},"rawBody":"---\nlabel: Content design can make or break an online experience. Always strive for writing that is clear, concise, and on-brand.\ntitle: Content\ndescription: Content design can make or break an online experience. Always strive for writing that is clear, concise, and on-brand.\ntabs: ['General', 'Guidance', 'Glossary']\n---\n\n### Content design can make or break an online experience. Always strive for writing that is clear, concise, and on-brand\n\n\n\nCapitalization\nVerb tense\nActive and passive voice\nFirst and second person\nFormal vs. casual tone\nCan, may, and might\n\n\n\n## Capitalization\n\nUse sentence-style capitalization in text and for all text elements in the UI except for proper nouns. Sentence style capitalizes only the first word of each sentence.\n\n#### Examples:\n\n- Cloud Foundry apps\n- Business models\n- Creating Boolean expressions\n- Planning network architectures\n- Carbon Design System\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 \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 \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 \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 \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 \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 \n \n
\n","fileAbsolutePath":"/tmp/42b44a0/src/pages/guidelines/content/guidance.mdx"}}}}