Merge pull request #772 from claycrenshaw/editorial-guidelines-2

QA / edits: Content, Iconography

Author: marijohannessen

src/content/guidelines/accessibility/overview.md

@@ -87,6 +87,7 @@ Color-blindness affects 8% of all men and 0.4% of women.
 
 #### What designers should think about
 
+
 - Run your design through a color-blind simulator. If the design doesn't work, try another approach. If you're working in Sketch, we recommend the [Stark](http://www.getstark.co/) plugin.
 <!-- - To view best practices for using color in Data Visualization, view the [Data Vis](/data-visualization/overview/colors) color page. -->
 

src/content/guidelines/content/general.md

@@ -1,31 +1,31 @@
 ---
-label: Guidelines
+label: Content design can make or break an online experience. Always strive for writing that is clear, concise, and on-brand.
 title: Content
 tabs: ['General', 'Guidance', 'Glossary']
 ---
 
 ## Voice and tone
 
-Using the appropriate voice and tone allows us to better connect and resonate with our users. Gone are the days when our users perceive their content experience as complex, distant, or disjointed. We've evolved and we now endorse a style that should feel like a conversation between friends – personal, relatable, clear, helpful, and engaging. Conversational style does not mean sloppy writing. It means creating content in a clear, concise way that anyone can understand. It means genuinely connecting with our users.
+Consistent voice and tone are crucial for connecting and resonating with users. What's the difference between voice and tone? One way to think about it is that voice is always consistent, but tone often changes depending on context.
 
-What is the difference between voice and tone? Simply put, we have the same voice all the time, but our tone often changes. Consider this: You have one voice, but you most likely use a certain tone when you are having coffee with friends and a different tone when you are meeting with your boss.
+**Voice** is the foundation for communicating about IBM products and delivering brand messages. At IBM, our voice expresses the core of our personality, while bringing comfort, ease, and a sense of connection to our users. Through careful use of the IBM voice, we help empower users to meet their business goals. 
 
-**Voice** is the foundation for communicating IBM Cloud products and brand message. Our voice expresses the core of our personality, while bringing comfort, ease, and a sense of connection to our users. Our goal is to empower our users to meet their business goals. Be consistent with voice across the platform.
+**Tone** conveys an attitude toward both the subject matter and the reader. All content – whether it's introductory text on the UI, an error message, or a topic in the docs – tells part of a bigger story. Good storytellers are skilled in two main areas: what they are saying (the substantive content) and how to say it to any given audience (the style and tone in which it is presented). Be a good storyteller.
 
-**Tone** conveys your attitude toward what you are writing about and who you are writing to. When you create content – whether it's introductory text on the UI, an error message, or a topic in the docs – you are essentially a storyteller. Good storytellers are experts in two main areas: what they are saying (the important information that the audience needs to know) and how to say it (the experience that they want to create for the audience). Be a good storyteller.
+## Conversational levels
 
-## Conversation levels
+Content should never feel complex, distant, or disjointed. Rather, it should feel like a conversation with a smart friend – personal, relatable, helpful, and engaging. Do not mistake conversational style for sloppy writing! Conversational content still needs to be clear, concise, and easy to understand. The best content creates a connection with the user.
 
-Here's how conversational you should be based on the six stages of the user journey:
+Here's a quick guide to conversational levels based on the six stages of the user journey:
 
-> **MOST: Discover, Try, Buy content**
+> **Less conversational: instructional content for how to complete a task (e.g. steps)**
 
-“Thanks for joining IBM Bluemix for your free 30-day trial. It's been great having you! Unfortunately, your Bluemix trial account, with IBMid name@domain, is now deactivated because your trial is over. While your account is deactivated, you can't access resources. Don't worry, your apps are not deleted.”
+“Go to Avatar icon > Account > Notifications to set up general account and spending notifications. Spending notifications are available only for Subscription and Pay-As-You-Go account owners.”
 
-> **MORE: Getting started interface content (for example, welcome), interface content for remaining experiences (Productive Use, Manage and Upgrade, Leverage and Extend, Get Support)**
+> **More conversational: _Getting started_ interface content (for example, welcome pages) and standard interface content for productive use, managing and upgrading, _leverage and extend_ content, and support**
 
-“To start using Bluemix, name your first organization. Think of an org as a project or team that shares resources, such as apps, databases, and other services. Orgs exist in geographic regions, so decide where you'd like to put your first one.”
+“To start using IBM Cloud, name your first organization. Think of an org as a project or team that shares resources, such as apps, databases, and other services. Orgs exist in geographic regions, so decide where you'd like to put your first one.”
 
-> **LESS: Instructional content (steps) for how to complete a task**
+> **Most conversational: _Discover, try, buy_ content**
 
-“Go to Avatar icon > Account > Notifications to set up general account and spending notifications. Spending notifications are available only for Subscription and Pay-As-You-Go Bluemix account owners.”
+“Watson Assistant comes pre-trained with industry-relevant content. It can make sense of your historical chat or call logs, and it has a visual dialog editor — meaning it's never been easier to get started (developers not required).”

src/content/guidelines/content/glossary.md

@@ -1,10 +1,10 @@
 ---
-label: Guidelines
+label: Content design can make or break an online experience. Always strive for writing that is clear, concise, and on-brand. 
 title: Content
 tabs: ['General', 'Guidance', 'Glossary']
 ---
 
-This section covers the approved **action labels** and **idioms** for use in the IBM products and documentation. Users rely on consistent labels for common actions to predict how to interact with an interface. Idioms are expressions that have a meaning different from the meaning of each word in the expression.
+This section covers the approved **action labels** and **idioms** for use in IBM products and documentation. Users rely on consistent labels for common actions to predict how to interact with an interface. Idioms are expressions that have a meaning different from what might be expected when taken literally.
 
 This section is a living document. When new terms are introduced, they will be added here.
 

src/content/guidelines/content/guidance.md

@@ -1,21 +1,29 @@
 ---
-label: Guidelines
+label: Content design can make or break an online experience. Always strive for writing that is clear, concise, and on-brand.
 title: Content
 tabs: ['General', 'Guidance', 'Glossary']
 ---
 
-## Capitalization
+<anchor-links>
+<ul>
+    <li><a href="#capitalization">Capitalization</a></li>
+    <li><a href="#verb-tense">Verb tense</a></li>
+    <li><a href="#active-and-passive-voice">Active and passive voice</a></li>
+    <li><a href="#first-and-second-person">First and second person</a></li>
+    <li><a href="#formal-vs-casual-tone">Formal vs. casual tone</a></li>
+    <li><a href="#can-may-and-might">Can, may, and might</a></li>
+</ul>
+</anchor-links>
 
-Good content design is consistent and coherent so that users can trust and predict how to interact with it. Details matter.
+## Capitalization
 
-Always capitalize proper names, such as United States. Use ALL CAPS for abbreviations, acronyms, and initials (for example, IBM and ASCII) and two-letter abbreviations (for example, AL, AK, and AZ), and for OK.
+Always capitalize proper names, such as United States. Use ALL CAPS for abbreviations, acronyms, and initials (for example, IBM and ASCII) and two-letter abbreviations (for example, AL, AK, and AZ), and for the word "OK."
 
 For specific capitalization rules for different element or component types, see the usage details for each individual element or component type.
 
 ### Sentence style
 
-Use sentence-style capitalization in text and for all text elements in the UI, except for table/grid column headers, headings for groups of toggles, and product names. Sentence style capitalizes only the first word of each sentence and proper nouns
-(such as names).
+Use sentence-style capitalization in text and for all text elements in the UI, except for table/grid column headers, headings for groups of toggles, and product names. Sentence style capitalizes only the first word of each sentence and proper nouns (such as names).
 
 #### Examples:
 
@@ -48,68 +56,82 @@ Only use headline-style capitalization for table/grid column headers and product
 
 #### Do not capitalize the initial letter of the following words:
 
-- articles, except as the first word
-- coordinating conjunctions
-- prepositions, except as the first or last word
+- articles, except as the first word (a, the, etc.)
+- coordinating conjunctions (but, and, etc. )
+- prepositions, except as the first or last word (to, for, etc.)
 
-## Do's & dont's
+## Verb tense
 
-These guidelines apply for developers and writers working with IBM Cloud UI and documentation.
+Use simple verbs and tenses, and keep sentences concise, simple, friendly, and punchy. Avoid the _continuous_, _perfect_, and _perfect continuous_ tenses in favor of the simple tenses whenever possible. 
 
-### Do use simple tense
+For example, for the verb "to write," the simplest tenses would be "You write," "You wrote," and "You will write." More complex tenses would include "You are writing," "You were writing," and "You will be writing." Even more complex tenses would say "You have written," "You had been writing," and "You will have been writing." 
 
-Use simple verbs and tenses, and keep sentences concise, simple, friendly, and punchy. Focus on the user's context and make content relevant. The more familiar you are with their context, the better you can communicate without using a lot of words.
-
-If you need to use past or future tense, avoid verb tenses with the words have, has, had, been, should, would, and will.
+These more complex tenses, when used excessively, can be more difficult for readers to parse.
 
 <grid-wrapper col_lg="8" flex="true">
-    <do-dont-example correct=true label="Future Tense" text='"The API returns a promise."'></do-dont-example>
-    <do-dont-example label='Future Tense' text='"The API will return a promise."'></do-dont-example>
+    <do-dont-example correct=true label="Future Tense" text='"The API will return a promise."'></do-dont-example>
+    <do-dont-example label='Future Tense' text='"The API will be returning a promise."'></do-dont-example>
+</grid-wrapper>
+<grid-wrapper col_lg="8" flex="true">
+    <do-dont-example correct=true label="Past Tense" text='"The API exceeded its limit."'></do-dont-example>
+    <do-dont-example label='Past Tense' text='"The API has exceeded its limit."'></do-dont-example>
 </grid-wrapper>
+
+## Active and passive voice
+
+The _active voice_ is direct and punchy, and emphasizes the subject of the verb. When a sentence is written in active voice, the subject performs an action, denoted by the verb—the subject "acts upon" the verb in these sentences. For example, "John ate the apple." In situations where either voice will work, generally choose the active voice for more directness.
+
 <grid-wrapper col_lg="8" flex="true">
-    <do-dont-example correct=true label="Past Tense" text='"The limit was exceeded."'></do-dont-example>
-    <do-dont-example label='Past Tense' text='"The limit has been exceeded."'></do-dont-example>
+    <do-dont-example correct=true label="Active Voice" text='"Next, the admin configures access privileges."'></do-dont-example>
+    <do-dont-example label='Passive Voice' text='"Next, access privileges are configured by the admin."'></do-dont-example>
 </grid-wrapper>
 
-### Do use active voice
+The _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 reconstructed into the passive voice. Thus, "_John ate_" cannot be constructed passively.  
 
-To convey a more natural tone, use active voice. People tend to speak in active voice unless they have a reason not to. For example, a good reason to use passive voice is to avoid sounding judgmental or blaming the user. Consider how a statement like, “You entered the wrong value,” which is active voice, might not be a well received error message.
+ The 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.  
 
 <grid-wrapper col_lg="8" flex="true">
-    <do-dont-example correct=true label="Active Voice" text='"In the Limits window, specify the minimum and maximum values."'></do-dont-example>
-    <do-dont-example label='Passive Voice' text='"The Limits window is used to specify the minimum and maximum values."'></do-dont-example>
+    <do-dont-example correct=true label="Passive Voice" text='"The database needs to be rebooted."'></do-dont-example>
+    <do-dont-example label='Active Voice' text='"Someone needs to reboot the database."'></do-dont-example>
 </grid-wrapper>
 
-### Do use second person
+## First and second person
 
-Engage your readers by using second person **(you, your)**. First person **(I, we, our)** focuses on the writer rather than the audience. People are interested in what they can do and how your story applies to their lives.
-One 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, for example “My Account” or “My Usage.” In explanatory text for the heading or label, switch to second person, for example _“Your usage is calculated from the 1st day of the month.”_
+Engage 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.
 
-### Don't be too formal or stuffy
+One 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.”_
 
-- Do not be afraid to use contractions once in a while. Decide whether they fit the context.
-- Occasionally begin sentences with **and, but or so.** This usage allows for shorter, scannable sentences. Do not overuse these devices, especially in instructional (steps) content.
-- For example, _“You can deploy an app to the cloud during lunch hour. And still have time to eat”_ is great for Discover, Try, Buy.
-- Occasionally 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 and hinder retrievability. Make sure headings that use questions are meaningful. In a UI, questions can be used in a confirmation prompt in a dialog box. For example: _“Do you want to close without saving?”_
-- 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.
+## Formal vs. casual tone
+
+While 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.
+
+- Don't be afraid to use **contractions**. When they fit the context and improve flow, go for it.
+- 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.
+- 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?”_
+- 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.
 
 <grid-wrapper col_lg="8" flex="true">
-    <do-dont-example correct=true label="Exclamation Points" text='"Your IBM Bluemix account is ready!"'></do-dont-example>
-    <do-dont-example label='Exclamation Points' text='"You have reached your usage limit!"'></do-dont-example>
+    <do-dont-example correct=true label="Exclamation Points" text='"Your IBM Cloud account is ready!"'></do-dont-example>
+    <do-dont-example label='Exclamation Points' text='"You have reached your usage limit!!"'></do-dont-example>
 </grid-wrapper>
 
-### Don't be overly mannerly
-
-Terms of politeness are superfluous, convey the wrong tone for technical material, and are not regarded the same way in all cultures.
+**Terms of politeness** are often overused, 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.
 
 <grid-wrapper col_lg="8" flex="true">
     <do-dont-example correct=true label='Using Please' description='Use "please" in a UI only when the user is being inconvenienced.' text='"Indexing might take a few minutes. Please wait."'></do-dont-example>
 </grid-wrapper>
 
+## Can, may, and might
+
+**Terms of ability** are often misused. Remember, "can" implies ability, and "may" implies permission (and sometimes uncertainty).
+
 <grid-wrapper col_lg="8" flex="true">
     <do-dont-example correct=true label="Ability" text='"You can use the command line interface to update your app."'></do-dont-example>
     <do-dont-example label='Ability' text='"You may use the command line interface to update your app."'></do-dont-example>
 </grid-wrapper>
+
+**Terms of possibility** 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."
+
 <grid-wrapper col_lg="8" flex="true">
     <do-dont-example correct=true label="Possibility" text='"You might need more advanced features when you are integrating with another app."'></do-dont-example>
     <do-dont-example label='Possibility' text='"You may need more advanced features when you are integrating with another app."'></do-dont-example>