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.
- Cloud Foundry apps
- Business models
- Creating Boolean expressions
- Planning network architectures
- Carbon Design System
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.
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.”
These more complex tenses, when used excessively, can be more difficult for readers to parse.
The API will return a promise.
The API will be returning a promise.
The API exceeded its limit.
The API has exceeded its limit.
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.
Next, access privileges are configured by the admin.
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.
Someone needs to reboot the database.
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.”
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!
You have reached your usage limit!!
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.
Please create a subscription account to get full access to the catalog.
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.
You may use the command line interface to update your app.
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.
You may need more advanced features when integrating with another app.