Content
Content design can make or break an online experience. Always strive for writing that is clear, concise, and on-brand
- Capitalization
- Verb tense
- Active and passive voice
- First and second person
- Formal vs. casual tone
- Can, may, and might
Capitalization
Use 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.
Examples:
- Cloud Foundry apps
- Business models
- Creating Boolean expressions
- Planning network architectures
- Carbon Design System
Active and passive voice
The 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.
Next, the admin configures access privileges.
Do use active voice when appropriate.
Next, access privileges are configured by the admin.
Don’t use passive voice when active voice will suffice.
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 constructed in the passive voice. Thus, “John ate” cannot be constructed passively.
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.
The database needs to be rebooted.
Do use passive voice when appropriate.
Someone needs to reboot the database.
Don’t use active voice when passive voice is more appropriate.
First and second person
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.
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.”
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.
Your IBM Cloud account is ready!
Do use exclamation points for positive messages.
You have reached your usage limit!!
Don’t use exclamation points for negative messages
Terms of politeness
Often 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.
Indexing might take a few minutes. Please wait.
Do use terms of politeness in a UI only when the user is being inconvenienced.
Please create a subscription account to get full access to the catalog.
Don’t use terms of politeness superfluously.
Can, may, and might
Terms of ability
These terms are often misused. Remember, “can” implies ability, and “may” implies permission (and sometimes uncertainty).
You can use the command line interface to update your app.
Do use ‘can’ to express ability.
You may use the command line interface to update your app.
Don’t use ‘may’ when you mean ‘can.’
Terms of possibility
These 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.”
You might need more advanced features when integrating with another app.
Do use ‘might’ to clarify possibility.
You may need more advanced features when integrating with another app.
Don’t use ‘may’ when ‘might’ will work.