Alfresco Voice

Writing for the user interface

One day I will find the right words, and they will be simple.

Jack Kerouac

Contents

WritingTone - how to writeLanguage - what to writeCapitalizationAbbreviationsTrademarks and copyrightsGlobal writingPunctuationCommon UI examplesTerm PickerMore information

Writing Clear, simple, and consistent user interface (UI) text makes users happy. The words we use can make or break the user experience. Think about the kind of person you want to work with, whether manager or a member of your team. Think of the language they use when they talk. They’re encouraging, honest, supportive, reliable, professional, and engaging. They guide and educate you. When they speak there’s no confusion or misunderstanding. They are clear and consistent. This is how to write for the user interface for Alfresco products. Use the examples and rules in this guide whenever you create new UI text, to provide a better and more consistent product for Alfresco’s customers.

Tone - how to write Every piece of writing in the UI should help the user towards achieving a goal. The tone of the writing is about how you make the user feel on their journey. Think how your ideal colleague would talk to you...

User Journey Alfresco says User feels

A fatal error occurred

Oops!

We hit a problem. Try refreshing your

browser.

This sounds really,

really bad L What do I do now?

What’s that supposed to mean?!? What do I

do now?

OK, doesn’t sound too

serious, I’ll try that.

✗ Too cold

✗ Too glib

✓ Just right

Tone - 4 tips

Who? Think about the person you’re writing for, the Alfresco product they’re using, and the level of knowledge they have. A developer can handle more technical language than an end-user, but they both want it to be kept as simple and clear as possible. Empower users by making them feel knowledgeable, rather than assuming a knowledge-level they may not have. Who this is for? How do they feel? What are they trying to do? What do they need to know?

How? Write it how you’d say it. When you write read it out loud. Is it clear? Does it make sense? Does a real person talk like this? Think of UI language as a two-way conversation between the user “you” and Alfresco “we”.

Be consistent If a term has already been established, then use it, don’t try to reinvent it. Stick to the same term within a process, for example, don’t talk about both “deleting” and “removing” if you mean the same thing. If you’re writing about something new then be creative, but stick to plain language.

Be professional Alfresco products are enterprise products and the language needs to reflect this. Strike a middle ground between over-formality and over-friendly. Write how you’d speak to a customer.

Tone - 5 examples

Be positive Encourage the user in the right direction, rather than telling them why they did something wrong.

Use numbers and letters only

You can’t use special characters

Do Don’t

Show empathy Understand the user’s situation. If they’re having problems, they want to be taken seriously.

We hit a problem.

Oops!

Do Don’t

Be helpful Give information on how to resolve an issue.

Use numbers and letters only

Incorrect name format.

Do Don’t

Be responsible Don’t blame the user. They haven’t done anything wrong, we just haven’t shown them how to do it right.

We didn’t recognize the email address or password

Your login details are incorrect

Do Don’t

Write actively Encourage the user to do things by writing actively. Writing actively means making the user the subject of the text. Nudge them to take the next step.

You haven’t added any users yet. Click Add Users to get started.

No users added

Do Don’t

You can switch off the shared link at any time

The sharing link can be disabled by switching it off

Do Don’t

Language - what to write

Use American English spelling Follow American-English spelling conventions, for example “ analyze” not “analyse”. This link has more details http://www.oxforddictionaries.com/words/british-and-american-spelling.

Write in the present Most UI actions happen immediately, so try to write to reflect that. When things do happen in the past or future, keep it simple.

Email sent

Email has been sent

Do Don’t

Write simply and directly Use plain language. Remove unnecessary words when possible, as they slow down the reading process and open up opportunities for confusion.

Upload new version

Would you like to upload your new version?

Do Don’t

Be concise, but also be clear Keep it simple, but not to the extent that the meaning isn’t clear.

2 confirmation emails sent

2 emails sent out

Do Don’t

Edit in Google Docs

Edit Online

Do Don’t

Use simple words If you have a choice of words you could use, go with the simplest option. Avoid technical terms where possible.

Loading video

Buffering

Do Don’t

Turn on this option

Enable this option

Do Don’t

Just give the information that’s necessary at a given point. Don’t feel the need to give too much information.

Assign a review task to a single reviewer.

Review and approval of content using Activiti workflow engine.

Do Don’t

Use contractions Most of the time we use contractions in daily speech, and your writing should reflect this. Occasionally you may avoid contractions if you really need to emphasis something, for example, “Do not click this button”.

it’s, can’t, won’t, you’re, don’t

it is, cannot, will not, you are, do not

Do Don’t

“1, 2, 3” not “one, two, three” Use numbers in place of words.

2 users added

Two users added

Do Don’t

Use generally understood words Avoid using terms that will only be understood by industry specialists. Use words and terms that will be understood by those outside Alfresco. If Alfresco have an established customer-facing term, then stick with it.

Cloud Sync Manager

Hybrid Cloud Manager

Do Don’t

Search Manager

Faceted Search Config.

Do Don’t

Avoid directional language Avoid any language that requires the user being able to see the screen or page layout.

Drag onto the layout area

Drag onto the panel below

Do Don’t

Capitalization “Title Style Caps” for actions, field labels, menu items and page titles. “Sentence style caps” for longer copy such as page or field descriptions and tooltips. “ALL-CAPS” - avoid at all times, except for abbreviations such as OK and CMIS. There is no grammatical right or wrong for this, the important thing is consistency, and existing Alfresco One content uses Title Caps for buttons, labels, and titles. Different standards have been set on other Alfresco products, for example Alfresco Process Services doesn’t use Title Style Caps, so always check the current standard in the product you’re writing for. You can make exceptions, for example if a button label is unusually long it may be better in sentence case. Joining words such as in, of, and to should always be lower case.

Do Don’t

Do Don’t

Do Don’t

Abbreviations Don’t use abbreviations unless they’re a common technical or product term. The exception to this is “OK”.

CMIS, ISO, API, SDK

etc., e.g., n.b., i.e.

Do Don’t

Trademarks and copyrights Don’t use them. There’s no need to put TM or similar marks when referring to third-party software. They’re untidy in the UI and they’re covered by the Help, which is a part of the product. Remember to spell product names correctly though, they’re usually Title Case.

Microsoft Office

Microsoft office TM

Do Don’t

Global writing The writing in the UI is translated into multiple languages. It’s also used by 1000’s of non-native English speakers of different cultures and backgrounds. Many of the writing guidelines support writing for these audiences, with the focus on clear, simple language.

Always leave the translations to the Localization Team, they know the rules for each language.

Steer clear of cultural references and slang. There is one established exception to this, which is to begin error messages with “We hit a problem”.

Done

Yeah, got it!

Do Don’t

And remember that humor doesn’t travel well. Keep it friendly and professional.

We hit a problem. Try refreshing your browser.

Well, it seems like that went all kinds of wrong!

Do Don’t

Punctuation Omit punctuation unless it’s necessary within full sentences.

Character Description

Period .

Use to punctuate full sentences, for example in body text in dialogs. Don’t use in fragments, single sentences, or buttons.

Comma ,

Use the serial, or Oxford comma. Do use “1, 2, 3, and 4” Don’t use “1, 2, 3 and 4”

Exclamation ! Avoid

Colon : Omit from labels, for example, fields in a form.

Semi-colon ; Avoid

Quotations “ “ Use “straight” not “curly” quotes. This helps avoid any problems during translation.

Apostrophes ‘

Use straight ‘ not curly ‘ apostrophes. This helps avoid any problems during translation. Tip – Assume you don’t need an apostrophe unless it’s a contraction such as can’t, don’t, or it’s (for it is). You don’t need an apostrophe for terms such as APIs or SDKs.

Ellipses … Use to indicate progress (“Uploading…”). No space before the ellipses. Omit from button labels and actions.

Em-dash — Avoid

En-dash – Use instead of a hyphen to indicate range, for example, “11.00am – 12.00pm”

Ampersand & Avoid

Common UI examples

Menu Action ItemsAction buttonsError messagesEmpty state placeholderTooltipsDialogsUpdate messagesLinks to the Help

Menu Action Items Active, imperative, and contextual. Encourage the user to move forwards with a specific action. Examples: Create File, Edit Properties, Upload New Version

Action buttons Active, imperative, and, if appropriate, contextual. Encourage the user to move forwards with a primary action. Think about the context. Try to avoid using generic terms that can be unclear. The button label should clearly say what action will be performed.

Do Don’t

Often a single word button label will describe the action.

Do

Error messages Don’t apologise, don’t try and hide from the issue. Accept responsibility, and if possible provide information for next steps. If necessary give error details, but make it contextual. Error dialogs

We hit a problem getting your search results. Try searching again.

There was an error loading search results

Do Don’t

The port you selected is already being used or you

don’t have permissions to use it. Try selecting another port.

It seems you do not have enough permissions to bind the port or the port is already taken by another

application.

Do Don’t

We hit a problem updating the task. Try copying and sharing the following details with your IT team.

Org.alfresco.repo.security.permissions.AccessDeniedE

xception: 00096029 Failed to update task with id’activiti$169859’

Org.alfresco.repo.security.permissions.AccessDeniedException: 00096029 Failed to update task with

id’activiti$169859’

Do Don’t Field errors Keep it simple, clear, and provide a next step.

Use numbers and letters only

You can’t use special characters

Do Don’t

Empty state placeholder If a screen or panel has no content, then explain why and give a gentle push as to what to do next.

You don’t have any tasks right now. Create a task for yourself or assign it to someone else.

No tasks

Do Don’t

Tooltips This is a good place to give contextually helpful information, whether it’s a short tip, or more in-depth. You can also give a link to the help (docs.alfresco.com) for even more information.

Dialogs Dialogs will usually be made up of title, body text, and action buttons. Make button actions clear. Don’t repeat information – think how you can give extra information in the body text.

Do Don’t

Do Don’t

Usually a Cancel label doesn’t cause confusion and no extra description is needed. OK buttons have been described as the “whatever” of buttons and are best avoided except for basic confirmation dialogs. See the Term Picker for more.

'image.jpg' willbedeletedandmovedtoyourTrashcan. Are you sure you want to delete 'image.jpg'?

The previous version of the file will still be available. The previous version of the file will still be available.

Update messages Don’t ask the user to be patient. Just tell them what’s happening, and if it’s not immediate then give an indication of how long it might take.

Update installing… this may take a few minutes

Please be patient, installing now

Do Don’t

Links to the Help Links to the Help can be used in tooltips and in the Admin Console to quickly access more information. If you add a link then give full details for accessibility reasons, and notify the UA Team so that it can be tracked for future updates. Make sure that the link points to the relevant topic in the correct version number at docs.alfresco.com by using the code available in the docsEdition context property in webscripts.

See Setting up high availability systems for more details.

Click here for more.

Do Don’t

Term Picker

Term Description

Alfresco Administrator See IT.

Back Use for multi-step processes, such as installation wizard.

Cancel Cancel an action. Use instead of “Kill” or “Abort”.

Create Use instead of “New” when the user is creating something. Can be appended with the thing that is being created, for example, “Create File”.

Dashboard One word, not Dash Board.

Done Use for the end of a multi-step process that ends with confirmation.

File Use instead of document, for example “Upload a File” or “File properties”. We are gradually transitioning away from using “document”, though there are still lots of occurrences, notably the Document Library.

File preview Use instead of Document Details or Doc Details page. These are internal terms and aren’t shown in the UI.

IT Use when referring the user to their IT resource, commonly in error messages. For example: “We hit a problem updating the task. Try sharing the following details with IT.” You can also use “IT team”.

Login / log in Don’t use it, use “Sign in”.

Logout / log out Don’t use it, use “Sign out”.

Next Use for multi-step processes, such as installation wizard.

OK Try to use a relevant action instead, such as “Delete” or “Save”. Can be used in basic confirmation dialogs instead of “Close”.

Properties Use instead of metadata.

Please Don’t use. Do say “Installing now”. Don’t say “Please be patient, installing now”.

Sorry Life’s too short, make amends by offering a solution instead.

Start Use when starting a service such as the Alfresco server, or when starting a new workflow. Don’t use “launch”, “initiate”, “execute”, or “invoke”.

Select For when the user is given an option, for example, “Select one or more tags”. Don’t use “click”, “choose”, or “choice”.

Tap Can be used as an alternative to “select” when you’re writing for a mobile app.

Toolbar Used to refer to the black action bar at the top of a the screen in Alfresco Content Services and Alfresco Process Services.

Trashcan One word, not Trash Can

Turn on / off Use instead of enable / disable.

web script This is two words, lowercase.

More information If you need more examples or suggestions then get in touch with the Alfresco UA and / or the UX teams at ua-team@alfresco.com and ux-team@alfresco.com. All new content MUST be reviewed by the UA team as early as possible, and definitely before release. This ensures consistency and helps avoid any issues during localization.