Essentials
Content Guide
Voice & 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.
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 Bluemix's product 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 your attitude toward what you are writing about and who you are writing to. When you create content – whether its 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.
Conversation Levels
Here's how conversational you should be based on the six stages of the Client Journey:
MOST: Discover, Try, Buy content
"Thanks for joining IBM Bluemix for your free 30-day trial. It's been great having you! Unfortunately, your Bluemix trial account, with IBMid [email protected], 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."
MORE: Getting started interface content (for example, welcome), interface content for remaining experiences (Productive Use, Manage and Upgrade, Leverage and Extend, Get 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."
LESS: Instructional content (steps) for how to complete a task
"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."
Do's and Don'ts
These guidelines apply for developers and writers working with the
Bluemix UI and documentation.
Do use simple tense.
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.
Future Tense:
“The API returns a promise.”
Future Tense:
“The API will return a promise.”
Past Tense:
“The limit has been exceeded.”
Past Tense:
“The limit was exceeded.”
Do use active voice.
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.
Active Voice:
“In the Limits window, specify the minimum and maximum values.”
Passive Voice:
“The Limits window is used to specify the minimum and maximum values.”
Do use 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.”
Don't be too formalor stuffy.
- 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 at 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:
Questions:
“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.
Exclamation Points
“Your IBM Bluemix account is ready!”
Exclamation Points
“You reached your usage limit!”
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.
Use please in a UI only when the user is being inconvenienced.
Using Please:
“Indexing might take a few minutes. Please wait.”
Instead of using may, use can to indicate ability or use might to indicate possibility.
Ability
“You can use the command line interface to update your app.”
Ability
“You may use the command line interface to update your app.”
Possibility
“You might need more advanced features when you're integrating with another app.”
Permission
“You may need more advanced features when you're integrating with another app.”
Capitalization
Good content design is consistent and coherent so that users can trust and predict how to interact with it. Details matter.
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.
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 (names).
Examples:
- Cloud Foundry apps
- Business models
- Creating Boolean expressions
- Planning network architectures
Headline style
Use headline-style capitalization for table/grid column headers, headings for groups of toggles, and product names. Headline style capitalizes words based on parts of speech.
Capitalize the initial letter of the following words:
- The first and last words of the text
- All nouns, pronouns, adjectives, verbs, adverbs, and subordinating conjunctions such as:
- after
- although
- because
- before
- how
- if
- than
- that
- though
- until
- when
- where
- whether
- while
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
This section covers the approved action labels and idioms for use in the Bluemix UI 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 is a living document. When new terms are introduced, they will be added here. To submit new terms, go to Proposed idioms and abbreviations for Bluemix.
If you're looking for the product glossary, go to Glossary terms for Bluemix.
COMMON ACTIONS
Add
Adds an existing object to a list, container, or system (for example, adding a document to a folder).
Combine Add with the object (for example, Add user, Add space, Add role, or Add privileges).Contrast with Insert and New.
Apply
Saves changes without closing the dialog. These properties often affect subsequent system behavior.
Use instead of Save Changes. Contrast with Save and Save As.Approve
Indicates the user agrees. In a business process, typically initiates the next step.
See Reject.IDIOMS
a la carte
(adverb) pertaining to separately itemized objects.
Context: Bluemix provides pay-as-you-go and subscription based pricing, a-la-carte and bundled services availability.app
(noun) a web or mobile device application.
Spell as shown, all lower case. In the doc, if for some reason it seems more appropriate to use application, use application for the first instance and then use app.Context: It's easy to delete apps to free up some spaces in Bluemix at any time.
COMMON ACTIONS
Back
Returns the user to the previous step in a sequence of steps, such as in a wizard.
Use instead of Previous. See Next and Finish.Browse
Assists the user in entering a file name or file path (for example, on a button or link next to an entry field). Typically opens a secondary window where the user can locate and select the desired directory and file.
IDIOMS
bestseller
(noun) a significantly successful product or service in the marketplace.
Context: Develop software for a cause or your company’s next bestseller.bet
(verb) to feel sure about something.
Context: We bet you have built some sweet apps by now.big savings
(phrase) a significant amount of money saved.
Context: You get big savings every month.
COMMON ACTIONS
Cancel
Stops the current action and closes the dialog.
Warn the user of any possible negative consequences of stopping an action from progressing, such as data corruption. See Reset.Clear
This action clears all the fields or selections. Also deletes the contents of a document, such as a log. Typically the default selection or value is re-established for controls that always have a selection or value, such as radio buttons.
Where appropriate, combine Clear with the object (for example, Clear contents, Clear fields, Clear all). Contrast with Delete and Remove.Close
Closes the current page or window (for example, closing a secondary window containing online help).
Do not use Close together with OK or Cancel actions. Contrast with Done. See Cancel.Copy
Creates new instances of the selected objects to a specific destination.
Combine Copy with the object being copied (for example, Copy folder) or the destination (for example, Copy to clipboard) if there are multiple possibilities. Use instead of Create like. Contrast with New.Create
Label for a button in a dialog or form that creates a new object. The settings in the dialog are applied to the object when it is created.
Use New to initiate the action of creating a new object. Use Create to confirm the action after any naming or configuration. Contrast with Add, Copy, and Insert.Customize
Allow a user to make desired changes.
IDIOMS
cold-blooded cyborg
(noun) a man-like robot with no feelings (to cloud its judgment) that flawlessly executes its mandate.
Context: Create apps with the efficiency of a cold-blooded cyborg.congrats
(noun) congratulations.
Context: Congrats on creating your new app!crash
(noun) the unexpected termination of a software function.
Context: Add the Mobile Quality Assurance service to your iOS app to view high value quality metrics, including information for crashes, bugs, user feedback, and user sentimentcrash
(verb) of software, to unexpectedly terminate.
Context: If a service crashes, the app might stop too.
COMMON ACTIONS
Delete
Destroys an existing object.
Combine Delete with the object to delete (for example, Delete column or Delete table). Contrast with Clear and Remove.Docs
Opens a separate window containing the landing page for Bluemix Docs.
Use only as link text from the console menu bar. See Learn More.Done
Indicates that the user has finished working in an environment (for example, editing templates) and wants to return to where he or she came from.
See Finish. Contrast with Close.IDIOMS
dev-to-dev
(phrase) developer to developer.
Context: Free support is available in our dev-to-dev forum.Docs
(noun) documentation.
Context: View docs.dream
(adjective) pertaining to something that is exceptionally gratifying, excellent, or beautiful.
Context: Build your dream app.
COMMON ACTIONS
Edit
Allows data or values to be changed.
Use instead of Modify unless you are modifying a table.Empty trash
Permanently deletes all files or objects that have been placed into a trash container.
See Move to trash.Export...
Saves data in a different format external to the system. Typically opens a secondary window for the user to specify the file type and destination (for example, storing table data as a set of comma-separated values).
See Import.
COMMON ACTIONS
Find
Moves the cursor to the next element matching the specified criteria (for example, view the next occurrence of a specific word within an email message).
Contrast with Filter and Search.IDIOMS
freebie
(noun) something given away at no cost.
Context: Enjoy freebies after the trial ends, and pay only for what you use beyond those.
COMMON ACTIONS
Get Help
Opens a search field from which the user can search for help information.
Use only as link text on Support widget from the console menu bar. See Docs and Learn more.IDIOMS
get in touch
(verb) to contact someone.
Context: The page also provides options to post your question to Stack Overflow, or to open a ticket by clicking Get in touch.
COMMON ACTIONS
IDIOMS
hackathon
(noun) an event that brings together developers to work intensively on a software project.
Context: Run a hackathon.have a hand in
(phrase) to be directly involved in the accomplishment or creation of something.
Context: If you're a developer, you now have a hand in creating the future.hit the ground running
(phrase) to immediately accomplish something when just starting to learn how to do it.
Context: Whatever your task, Bluemix contains everything you need to hit the ground running.
COMMON ACTIONS
Import...
Transforms data or objects from an external source. Typically opens a secondary window for the user to locate the external source.
Context: Creating a new table based on comma-separated values contained in a separate file.See Export.
Insert
Adds an element at a particular position in an ordered view.
Context: Adding a picture to the body of a document or inserting a record into a table.Contrast with Add and New.
IDIOMS
in a flash
(phrase) quickly, immediately.
Context: Deploy and test your app in a flash.
COMMON ACTIONS
Learn more
Opens additional, highly contextual information. Insert at the end of inline text or hover text where more information follows but does not fit in the current context.
If space permits, combine Learn more with meaningful text that describes the content you're pointing to. For example, if your user needs some best practices to manage apps in multiple regions, you could use Learn more about regions.Log in
Enters a site or application. This choice typically opens a form for entry of credentials. Also used on the submission button after users enter their credentials.
Use instead of Sign in. See Log out.IDIOMS
lost in space
(phrase) to be hopelessly adrift with no chance of return, unlocatable, lost to the world.
Context: This page seems to be lost in space.
COMMON ACTIONS
Move
Transfers an object from one container (for example, folder, activity, or page) to another.
Move to trash
A soft delete. Moves a file or object to an area from where it can later be permanently deleted or recovered.
Use instead of Delete or Recycle bin. See Empty trash.IDIOMS
meetup
(noun) an informal gathering.
Context: Plan anything, even the monthly meetup.muscle
(noun) the metaphorical strength or physical power of something.
Context: Whether startup or enterprise, your apps are supported by the muscle of an enterprise-ready cloud.
COMMON ACTIONS
New
Starts the creation of a new object. New either creates the object immediately or opens a dialog or set of fields where the user can enter properties.
Combine New with the object to create (for example, New user or New column). See Create. Contrast with Add, Copy, and Insert.Next
Advances the user to the next step in a sequence of steps, such as in a wizard.
See Back and Finish.IDIOMS
N/A
(adjective) not applicable, not available.
Spell as shown, all upper case.
COMMON ACTIONS
OK
Completes the current task.
The best practice is to use a label corresponding to the requested action, such as Save or Create. Use OK only when such a label is not available.IDIOMS
oh no!
(phrase) used to indicate shock.
Context: Oh no! The free trial expired.on prem, on-prem
(adjective) on premises, on-premises.
Context: Incrementally port application features across on-prem platforms and clouds with consistent services.oops
(expression) used to indicate an accident or a mistake.
Context: Oops, sorry, the HTML5 File APIs are not fully supported in this browser.ops
(noun) operations.
Context: Bluemix mobile cloud services help developers minimize ops and maintenance cost.org
(noun) organization.
Context: Change to a different org.
COMMON ACTIONS
Play
Starts audio, video, or an animation.
Post
Adds a new comment to an online community or adds status to a log or record.
If you are editing an existing comment, use Save instead.Preview
Shows how an object or content will appear with formatting applied before the content is published or distributed. Alternatively, provides an incomplete display of an existing object without leaving the current context.
Sends a copy of the currently selected object or the object in view to the printer.
COMMON ACTIONS
Refresh
Reloads the view of an object when the displayed view has become unsynchronized with the source.
Likely used only as a tooltip on an icon button.Reject
Indicates the user does not approve. In a business process, typically blocks the process from proceeding to the next step.
See ApproveReply
Indicates or completes a response to an email or a comment.
Remove
Removes an object from a list or container but the object is not destroyed as a result of the action. Often requires one or more objects to be selected.
Where appropriate, combine Remove with the object that will be removed (for example, Remove user, Remove role, Remove privileges). Contrast with Delete and Clear.Reset
Reverts values back to their last saved state. The last saved state includes the values stored the last time the user clicked Apply. Does not close the dialog or window.
See Restore defaults, Undo, and Cancel. Contrast with Restore.Restore all
Completes a restore operation on all files or objects in a given system or container.
Contrast with Restore.Run
Runs a task, job, activity, or program.
Use instead of Execute.IDIOMS
ready for takeoff
(phrase) prepared for use.
Context: Your app is ready for takeoff!
COMMON ACTIONS
Save
Saves pending modifications made to a file or document. Does not close the window or panel.
Contrast with Apply.Save As...
Creates a new object based on the state of the object currently being viewed. The user names the new object and typically identifies its location.
Search
Returns all objects (for example, files, names, or documents) within a defined set (for example, in a folder, directory, database, or the internet) that match some specified criteria.
Contrast with Find and Filter.Select
Selects data from a table.
Select all
Adds all objects in the view to the selection set or checks all check boxes.
Contrast with Clear.Send
Transfers an email or other information to the recipient.
Sign up
Creates a user account or registers a user in a system.
Use instead of Register.Start
Deploy an app or service to its development or production environment so that it can be used.
Use instead of Launch.Sort
Sorts a list or table column.
Likely used only as a tooltip on an icon button. Can be used without 'Ascending' or 'Descending' only if the order can be provided to a screen reader in the code for accessibility.Submit an idea
Opens a separate window containing the IBM Cloud Ideas portal.
Use only as link text on Support widget from the console menu bar.IDIOMS
skunkworks
(noun) a high priority, often secret, project taken on by a small team without constraints from management.
Context: Start a skunkworks.startup
(noun) a newly established business.
Context: Whether startup or enterprise, your apps are supported by the muscle of an enterprise-ready cloud.start from scratch
(phrase) to start from the beginning, to start from nothing.
Context: Choose a package of sample code and services, or start from scratch.sweet
(adjective) pertaining to something that is considered excellent, awesome, or cool.
Context: We bet you have built some sweet apps by now.sync
(noun) synchronize.
Spell as shown (not synch).Context: Download this .zip file template application or sync with the template source repository by copying and pasting the Git URL to a command line.
COMMON ACTIONS
Top
Returns to the top of the page.
Use instead of Back to top.IDIOMS
test drive
(noun) a test or evaluation of a piece of software for a specified amount of time.
Context: You have 1 day left in your Bluemix test drive.time flies
(phrase) time passes quickly.
Context: Wow, time flies!
COMMON ACTIONS
Undo
Reverts to the state before the most recent changes made by the user. Repeated use successively reverts to prior states in reverse chronological order. Applies to changes in data and not to changes made to the view.
Not all actions, such as Save, can be undone. See Redo, Reset, and Restore defaults.Update
Label for a button in a dialog or form for editing an object. The settings in the dialog are applied to the object when it is updated.
See Edit.IDIOMS
unfavorite
(verb) to change the status of an item that was previously marked as a favorite. (adjective) an item that is not a favorite.
Context: Unfavorite.
COMMON ACTIONS
View details
Presents additional information or properties for the object.
IDIOMS
voila
(expression) draws attention to something that has been accomplished or gained.
Context: Runtime and container usage is charged based on two things. One, how much memory your runtime or container uses, and two, the duration that memory is used. Multiply the two together, and voila! The GB-hour.
IDIOMS
wow!
(expression) used to show astonishment, delight, or admiration.
Context: Wow, time flies!