Writing style

The way you phrase an error message, the way you write help documentation, and even the text you choose for a button have big impacts on the usability of your app. Writing style can make a big difference between an awful user experience and a better one.

Voice and tone principles

Research shows that people respond best to a writing style that's friendly, helpful, and concise. As a part of this research, Microsoft developed three voice and tone principles that we apply across all our content, and are an integral part of Fluent design.

Be warm and relaxed

Above all else, you don't want to scare off the user. Be informal, be casual, and don't use terms they won't understand. Even when things break, don't blame the user for any problems. Your app should take responsibility instead, and offer welcoming guidance that puts the user's actions first.

Be ready to lend a hand

Always show empathy in your writing. Be focused on explaining what's going on and providing the information that the user needs, without overloading them with unnecessary info. And if possible, always provide a solution when there's a problem.

Be crisp and clear

Most of the time, text isn't the focus of an app. It's there to guide people, to teach them what's going on and what they should do next. Don't lose sight of this when writing the text in your app, and don't assume that users will read every word. Use language that is familiar to your audience, make sure it's easy to understand at a glance.

Lead with what's important

Users need to be able to read and understand your text at a glance. Don't pad your words with unnecessary introductions. Give your key points the most visibility, and always present the core of an idea before you add onto it.

Select filters to add effects to your image.

If you want to add visual effects or alterations to your image, select filters.

Emphasize action

Apps are defined by actions. Users take action when they use the app, and the app takes action when it responds to the user. Make sure your text uses the active voice throughout your app. People and functions should be described as doing things, instead of having things done to them.

Restart the app to see your changes.

The changes will be applied when the app is restarted.

Short and sweet

Users scan text, and will often skip over larger blocks of words entirely. Don't sacrifice necessary information and presentation, but don't use more words than you have to. Sometimes, this will mean relying on many shorter sentences or fragments. Other times, this will mean being extra choosy about the words and structure of longer sentences.

We couldn't upload the picture. If this happens again, try restarting the app. But don't worry — your picture will be waiting when you come back.

An error occurred, and we weren't able to upload the picture. Please try again, and if you encounter this problem again, you may need to restart the app. But don't worry — we've saved your work locally, and it'll be waiting for you when you come back.

Style conventions

If you don't consider yourself to be a writer, it can be intimidating to try to implement these principles and recommendations. But don't worry — using simple and straightforward language is a great way to provide a good user experience. And if you're still unsure how to structure your words, here are some helpful guidelines. And if you want more information, check out the Microsoft Style Guide.

Addressing the user

Speak directly to the user.

• Always address the user as "you."
• Use "we" to refer to your own perspective. It's welcoming and helps the user feel like part of the experience.
• Don't use "I" or "me" to refer to the app's perspective, even if you're the only one creating it.

We couldn't save your file to that location.

Abbreviations

Abbreviations can be useful when you need to refer to products, places, or technical concepts multiple times throughout your app. They can save space and feel more natural, as long as the user understands them.

• Don't assume that users are already familiar with any abbreviations, even if you think they're common.
• Always define what a new abbreviation means the first time the user will see it.
• Don't use abbreviations that are too similar to one another.
• Don't use abbreviations if you're localizing your app, or if your users speak English as a second language.

The Windows app design guidance is a resource to help you design and build beautiful, polished apps. With the design features that are included in every Windows app, you can build user interfaces (UI) that scale across a range of devices.

Contractions

People are used to contractions, and expect to see them. Avoiding them can make your app seem too formal or even stilted.

• Use contractions when they're a natural fit for the text.
• Don't use unnatural contractions just to save space, or when they would make your words sound less conversational.

When you're happy with your image, select save to add it to your gallery. From there, you'll be able to share it with friends.

Periods

Ending text with a period implies that that text is a full sentence. Use a period for larger blocks of text, and avoid them for text that's shorter than a complete sentence.

• Use periods to end full sentences in tooltips, error messages, and dialogs.
• Don't end text for buttons, radio buttons, labels, or checkboxes with a period.

You’re not connected.

• Check that your network cables are plugged in.
• Make sure you're not in airplane mode.
• See if your wireless switch is turned on.
• Restart your router.

Capitalization

While capital letters are important, they're easy to overuse.

• Capitalize proper nouns.
• Capitalize the start of every string of text in your app: the start of every sentence, label, and title.

Which part is giving you trouble?

• I forgot your password.
• It won't accept password.
• Someone else might be using my account.

Error messages

When something goes wrong in your app, users pay attention. Because users might be confused or frustrated when they encounter an error message, they're an area where good voice and tone can have a particularly significant impact.

More than anything else, it's important that your error message doesn't blame the user. But it's also important not to overwhelm them with information that they don't understand. Most of the time a user who encounters an error just wants to get back to what they were doing as quickly and as easily as they can. Therefore, any error message you write should:

• Be warm and relaxed by using a conversational tone and avoiding unfamiliar terms and technical jargon.

• Be ready to lend a hand by telling the user what went wrong to the best of your ability, by telling them what will happen next, and by providing a realistic solution they can accomplish.

• Be crisp and clear by eliminating extraneous information.

You’re not connected.

• Check that your network cables are plugged in.
• Make sure you're not in airplane mode.
• See if your wireless switch is turned on.
• Restart your router.

Dialogs

Many of the same advice for writing error messages also applies when creating the text for any dialogs in your app. While dialogs are expected by the user, they still interrupt the normal flow of the app, and need to be helpful and concise so the user can get back to what they were doing.

But most important is the "call and response" between the title of a dialog and its buttons. Make sure that your buttons are clear answers to the question posed by the title, and that their format is consistent across your app.

Which part is giving you trouble?

1. I forgot my password
2. It won't accept my password
3. Someone else might be using my account

Buttons

Text on buttons needs to be concise enough that users can read it all at a glance and clear enough that the button's function is immediately obvious. The longest the text on a button should ever be is a couple short words, and many should be shorter than that. When writing the text for buttons, remember that every button represents an action. Be sure to use the active voice in button text, to use words that represent actions rather than reactions.

• Install now
• Share

Spoken experiences

The same general principles and recommendations apply when writing text for spoken experiences, such as Cortana. In those features, the principles of good writing are even more important, because you are unable to provide users with other visual design elements to supplement the spoken words.

• Be warm and relaxed by engaging your users with a conversational tone. More than in any other area, it's vital that a spoken experience sound warm and approachable, and be something that users aren't afraid to talk to.

• Be ready to lend a hand by providing alternative suggestions when the user asks the impossible. Much like in an error message, if something went wrong and your app isn't able to fulfill the request, it should give the user a realistic alternative that they can try asking, instead.

• Be crisp and clear by keeping your language simple. Spoken experiences aren't suitable for long sentences or complicated words.

Accessibility and localization

Your app can reach a wider audience if it's written with accessibility and localization in mind. This is something that can't only be accomplished through text, though straightforward and friendly language is a great start. For more information, see our accessibility overview and localization guidelines.

• Be ready to lend a hand by taking different experiences into account. Avoid phrases that might not make sense to an international audience, and don't use words that make assumptions about what the user can and can't do.

• Be crisp and clear by avoiding unusual and specialized words when they aren't necessary. The more straightforward your text is, the easier it is to localize.

Techniques for non-writers

You don't need to be a trained or experienced writer to provide your users with a good experience. Pick words that sound comfortable to you — they'll feel comfortable to others, too. But sometimes, that's not as easy as it sounds. If you get stuck, these techniques can help you out.

• Imagine that you're talking to a friend about your app. How would you explain the app to them? How would you talk about its features or give them instructions? Better yet, explain the app to an actual person who hasn't used it yet.

• Imagine how you would describe a completely different app. For instance, if you're making a game, think of what you'd say or write to describe a financial or a news app. The contrast in the language and structure you use can give you more insight into the right words for what you're actually writing about.

• Take a look at similar apps for inspiration.

Finding the right words is a problem that many people struggle with, so don't feel bad if it's not easy to settle on something that feels natural.