Voice and tone

Voice and tone

The right voice and tone sets the basic principles for effective communication with our users.

For a comprehensive guide on writing content, please check writing.cumulocity.com.

Voice

Voice is how we communicate with our users across our brand, marketing materials and company products. Our voice is human. It’s familiar, friendly and clear. Our priority is to explain our products and to help our users get their work done.

Basic voice principles:

  • We are humans

  • We are friendly

  • We are professional

  • We are clear

Tone

The tone might be seen as the subset of our voice communication. Our tone is professional yet informal but above all clear.

Consider the user's specific situation and task's context when you’re writing. Is the user confused and seeking help on a specific issue?

Is he overwhelmed with information in a particular place on the application and just need the most basics hints to accomplish some task?

Once you have an idea of the emotional state, you can adjust your tone accordingly depending on the situation.

How to communicate

  • Write simple

    Time is limited, people are usually in a rush. Keep your copywriting simple.
    Don't say "Click on the button with the label 'Device' on the uppermost right-hand side of the screen."
    when you can say "Click 'Device' on the top right."


  • Be helpful

    While we work every day to make it simpler and easier, Cumulocity is a big place. It might be easy for people to get confused on some occasions. Always try to set the context on what's being done and provide possible solutions if something went wrong.


  • Active and positive voice

    Instead of "The device might not be 'On'.", use "The device is 'Off'."
    Instead of "Maybe you should check the alarms to get more details.", use "Check the alarms for details."
    Instead of "This dashboard was not properly configured.", use "Please configure this dashboard."


  • Avoid jargon

    Our products and services can be very technical but that doesn't mean that all of our clients are familiar with the technical lingo. Be detailed as you need but avoid technical terms. Explain a particular task like you would to a "5-year-old", without being condescending.


  • Write global

    Even if you're writing in English, don't forget that our customers are global. Do proper cultural research to avoid problems without toning down your message.


  • Be clear

    Our product can be very complex, it is very important to make things clear to avoid misinterpretations and wasting time from our customers and support team.

UI terminology

Common terms used across Cumulocity's user interface:

Term Usage Example
add

To create a new object of a specific type and add it to a list, object, etc.

Actually, creating and adding are two separate steps but in the UI both terms usually refer to the process of creating AND adding.

Prefer “create” if there's a clear first-create-then-add mechanism. See also create.

Add group
apply To commit a set of changes or pending transactions made in a secondary window. Apply configuration snapshot
cancel To halt an operation or process and return to the prior state. Cancel all pending operations
change Replace one existing thing with another.
See also edit, update.

Password has been changed

Tenant policy name changed to "{{name}}"

clear To remove content from a “container” (e.g. file, field) without deleting the container itself. Not to be mixed up with “delete” or “remove”.
Do not use clear, if from a user perspective an object is deleted.
See also delete, remove.

Clear log file

Clear date range

click To position the cursor over an object and then press and release a mouse button.
See also press.

Click below to start

complete To finalize a process.
Do not use “finish”.

Could not complete the operation

create Used to refer to the process of creating an object from scratch.
Often “add” is used instead since the object is usually created and added in one step.
Do not use “generate”.
See also add.

Application has been created

delete To remove an object permanently and remove it from a list.
See also remove.

User has been deleted

Are you sure you want to delete…

double-click To press and release a mouse button twice in rapid succession.
Mind the spelling with a hyphen.

Double-click to add points and set the area

duplicate To create a second instance of an object to be used as a “template” for a new instance.

Duplicate Smart rule

Duplicate application

edit Change an existing object in an editor.
Do not use “modify”. See also change, modify, update.

Edit dashboard

Click to edit

Edit

email “E-mail” and “email” are both correct ways to spell the same word.
In Cumulocity software and documentation use “email” without a hyphen.

Email address

Email settings

Email

enter Typing something into a text box, etc.

Enter your password

must Use “must” in instructions if it is mandatory to provide a value or use certain characters.
Do not use “should” for anything that is mandatory.
See also change, modify, update.

The following mandatory fields must be included

Name must be unique among coils and discrete inputs

press To press and release a keyboard key.
See also click.

TPress CTRL/CMD+C to copy

realtime/real-time/real time Actually, “real time” is the noun and “real-time” the adjective.
To avoid mixing it up, in Cumulocity software and documentation “realtime” is used for both.

realtime

remove Remove an object from a list without deleting it permanently.
See also delete.

Remove device from group

save To store data that has been provided through adding or editing objects.
Prefer over store in the UI.

Inventory role saved

Save to library

Save

select To be used in the context of selecting a checkbox or selecting an entry from a dropdown list, menu of choice.
Do not use “check” when referring to selecting a checkbox.
Prefer over choose in the UI.

Select a device type

set up Use for adding software to a system.
When using the verb set up, spell with two words.
Set up and install are generally interchangeable.
Setup as a noun is a single word.

Set up demo

Set up application

should Use “should” if an instruction is just a recommendation rather than referring to mandatory input.
See also must.

Page should be reloaded to correctly display…

successfully Avoid using “successfully in messages like “Created/updated/deleted successfully” where it is usually redundant.
In some occasions it might be meaningful though, i.e. in a bulk process which might have been completed “successfully” or with errors.

Device connected

Application deleted

update Persist a change that has been made in the database.
See also edit, change

Global role updated

clone Do not use. Clone is technical and may have negative connotations.

Use duplicate instead.

finish Do not use

Use complete instead.

generate Do not use

Use create instead.

modify Do not use

Use change, edit or update instead.

store Do not use

Use save instead.

Button labeling

Always use sentence case

Avoid using exclamations like "Ok" and "No", because they can be misleading and you'll have to provide some explanation

When using icons, keep the label whenever possible, except when the action's context and/or icon make it unmistakable

Make sure to always use the title attribute

Do.



Don't.



WYLTIWLT

A practical solution is to say that the words on a button must make sense after both the interrogative “Would you like to…?” (where the publisher speaks) as well as the conditional “I would like to…” (where the user speaks).
It's the “Would you like to? / I would like to” test, or WYLTIWLT (pronounced “wilty-wilt” – a bit like WYSIWYG) for short.

Form elements

The placeholders shouldn't be left empty if you can use it to help the user. Be helpful by providing an example of the expected input.

Do.

Don't.

Tab labeling

Ensure that the labels show a clear relationship between views

Favor nouns over verbs, for example, Data explorer, Sub-assets, and Measurements

Avoid generic labels such as "General" or "Advanced"

Use sentence case

Always fill in the attribute title with the tab label

On page-level tabs always provide an icon prefixing the label

Action-bar button labeling

The action bar is a toolbar with a horizontal row of buttons or links to interact with the current view.

Use a similar approach as to the button labeling

Use sentence case

If needed, provide more info in the title attribute, for example in "Full screen" the title attribute is "Toggle full screen"

Always provide an icon prefixing the label

Do.

Don't.

Plus button

Placed in the main header, the plus button holds a dropdown with shortcuts for adding or creating actions.

Reflect the action to be performed together with the subject, for example "Create report" or "Add group"

Always prefix it with the corresponding icon

Always fill in the attribute title with the action label

Prompts

Choose the proper icon

Provide a meaningful title

Always make sure you write a short message. The user has to understand what's happening and realize their options.

Do.

Don't.

Validation

Provide concise and straight to the point messages. You can use abbreviations.

Do.

Don't.