Before the docs: writing for user interfaces

Before the docsWriting for user interfaces

Beth Aitman@baitman

Why does UI text matter?Introduction - Microcopy - Help - Errors

Why does UI text matter?

The UI comes first.

Introduction - Microcopy - Help - Errors

Introduction - Microcopy - Help - Errors

Introduction - Microcopy - Help - Errors

Introduction - Microcopy - Help - Errors

It’s not one or the otherIntroduction - Microcopy - Help - Errors

It’s not one or the other

Docs and UI support each other.

Introduction - Microcopy - Help - Errors

Three main areas

1. Microcopy2. Embedded help3. Error messages

Introduction - Microcopy - Help - Errors

Introduction - Microcopy - Help - Errors

Introduction - Microcopy - Help - Errors

Introduction - Microcopy - Help - Errors

First, microcopyIntroduction - Microcopy - Help - Errors

Introduction - Microcopy - Help - Errors

Introduction - Microcopy - Help - Errors

Text makes UIs meaningful

from https://signalvnoise.com/posts/3404-reminder-design-is-still-about-words

Introduction - Microcopy - Help - Errors

Text makes UIs meaningful

from https://signalvnoise.com/posts/3404-reminder-design-is-still-about-words

Introduction - Microcopy - Help - Errors

Microcopy is difficult

“Naming things is hard!”

Introduction - Microcopy - Help - Errors

Introduction - Microcopy - Help - Errors

Introduction - Microcopy - Help - Errors

Introduction - Microcopy - Help - Errors

Introduction - Microcopy - Help - Errors

Introduction - Microcopy - Help - Errors

Introduction - Microcopy - Help - Errors

Introduction - Microcopy - Help - Errors

Three strategies for microcopy

1. Think from the user perspective2. Choose names they can understand3. Experiment with phrasing

Introduction - Microcopy - Help - Errors

1. Think from the user perspective

Explain what a feature does, not how it works

Introduction - Microcopy - Help - Errors

Introduction - Microcopy - Help - Errors

For buttons, think actionsIntroduction - Microcopy - Help - Errors

Not this!

For buttons, think actionsIntroduction - Microcopy - Help - Errors

2. What’s it normally called?What do users call it?What will they understand?

Introduction - Microcopy - Help - Errors

Introduction - Microcopy - Help - Errors

Introduction - Microcopy - Help - Errors

Introduction - Microcopy - Help - Errors

Introduction - Microcopy - Help - Errors

3. Experiment with phrasing

Introduction - Microcopy - Help - Errors

3. Experiment with phrasing

Try explaining it in a sentence.

Introduction - Microcopy - Help - Errors

Introduction - Microcopy - Help - Errors

Introduction - Microcopy - Help - Errors

… and embedded help is there if you need it.

Introduction - Microcopy - Help - Errors

Introduction - Microcopy - Help - Errors

Introduction - Microcopy - Help - Errors

Introduction - Microcopy - Help - Errors

Embedded helpIntroduction - Microcopy - Help - Errors

Introduction - Microcopy - Help - Errors

Introduction - Microcopy - Help - Errors

Introduction - Microcopy - Help - Errors

Embedded help

- What do you include?- When do you use docs?- Where do you put help?- Styles

Introduction - Microcopy - Help - Errors

What goes in embedded help?

“What does your user need to know to complete their task?”

Introduction - Microcopy - Help - Errors

Introduction - Microcopy - Help - Errors

Introduction - Microcopy - Help - Errors

Introduction - Microcopy - Help - Errors

Introduction - Microcopy - Help - Errors

Introduction - Microcopy - Help - Errors

Don’t overload peopleIntroduction - Microcopy - Help - Errors

Embedded help vs docs

- If it’s necessary information:probably keep it in the UI

- If it’s huge:summarise, then link to a doc

Introduction - Microcopy - Help - Errors

Show it in the relevant placeIntroduction - Microcopy - Help - Errors

Introduction - Microcopy - Help - Errors

Introduction - Microcopy - Help - Errors

Embedded help styles

There are tons.

Introduction - Microcopy - Help - Errors

Embedded help styles

There are tons. But I like:- inline help

Introduction - Microcopy - Help - Errors

Embedded help styles

There are tons. But I like:- expandable questions

Introduction - Microcopy - Help - Errors

Embedded help styles

There are tons. But I like:- hover text

Introduction - Microcopy - Help - Errors

Embedded help styles

There are tons.So experiment!

Introduction - Microcopy - Help - Errors

In summary

- find out what user needs to complete task

- don’t overload with information- show help in a relevant place and time

Introduction - Microcopy - Help - Errors

Error messagesIntroduction - Microcopy - Help - Errors

Error messages are easy!

I’ve got a formula.

Introduction - Microcopy - Help - Errors

- what went wrong- consequences- how to fix it

Introduction - Microcopy - Help - Errors

- what went wrong- consequences- how to fix it

Introduction - Microcopy - Help - Errors

Introduction - Microcopy - Help - Errors

Introduction - Microcopy - Help - Errors

Introduction - Microcopy - Help - Errors

- what went wrong- consequences- how to fix it

Introduction - Microcopy - Help - Errors

Introduction - Microcopy - Help - Errors

Introduction - Microcopy - Help - Errors

- what went wrong- consequences- how to fix it

Introduction - Microcopy - Help - Errors

Introduction - Microcopy - Help - Errors

Introduction - Microcopy - Help - Errors

Introduction - Microcopy - Help - Errors

Introduction - Microcopy - Help - Errors

- what went wrong- consequences- how to fix it

(and leave it out if it doesn’t apply)

Introduction - Microcopy - Help - Errors

In summary...

- Experiment with naming to get your microcopy right.

- Support users with embedded help in the UI, but be ready to link to docs.

- Use the formula for error messages!

Introduction - Microcopy - Help - Errors

One last thing!

uiwriting.tumblr.com@baitman

Thanks for listening :)If you have questions/opinions, talk to me after, or get in touch!

uiwriting.tumblr.com@baitman