#ui writing

[revisionthing]

A community for tech writers

Share ideas

Ask questions

Get extra eyes

Share tools

Rib product managers

Comisserate

Ideate

Incubate

Peer review

Share solutions

Grow a network

Join us: https://www.tumblr.com/join/bYNj2jMH

[uiwriting]

Information design for a Slack bot

One of our developers was trying to make it easier for our colleagues, after they’ve reviewed a pull request (PR), to keep updated on that PR’s status. This developer was building a Slack bot to do this. I offered to help - it seemed like an interesting information design problem.

Their initial design

This isn’t ideal. It needs a legend to explain what all the symbols mean: the concepts they’re trying to communicate are not simple, and just can’t be summed up neatly by an icon. It’s also hard to get information out of this at a glance.

It turned out that our developer assumed they needed to use a table - and because they were using a table, they had to use emoji-only headers, otherwise it wouldn’t fit horizontally.

(For those not familiar with Git and GitHub: the first bit in the pull request column (eg “platform”, “everything”) is the name of the code repository; the number is the ID of the pull request; and the rest is the pull request’s title.)

A quick fix

Firstly, I had a go at a minimal redesign. I felt like the table was causing problems, so I tried to find a different format for the information:

I wanted to do something that would be low effort to implement, making it really easy for our developer to improve the information design. It can be done totally with text and basic markup: doesn’t need any fanciness to implement.

I also wanted to keep some elements of their design. A total redesign can come across as harsh criticism, and I was basically rewriting all the text they wrote. So I kept some of the clearer emojis, and some of the structure (using “=” signs for the dividers).

This redesign takes up more space than the original. But that’s fine! Conciseness is important, but clarity has to win out. This design doesn’t require a legend, because it uses clear text labels to replace most of the emojis. It uses phrases (eg “5 new commits”) rather than numbers in a table.

And the whole thing is much more readable. The users of this bot are trying to find out what’s changed since their last review, so they know what they need to do. This design focuses on efficiently getting them that information.

Something a bit fancier

Then I discovered attachments! This was pretty exciting, because you can use them to format bot messages in a much nicer way.

I actually really enjoyed using Slack’s documentation around these. The Introduction to messages gives an overview of what’s possible with messages and attachments, and also gives a sense of what the features are for. There are some helpful Guidelines for building messages that look more at the UX side, and what best practice looks like - particularly if you’re implementing a more complicated workflow. Then the page on Attachments is what helped me understand the range of possibilities of the format.

But my favourite bit was the Message builder. It lets you really quickly prototype a message (including attachments), refreshing whenever you make a change so you can see the effect. I had a lot of fun playing around with it, it’s a great tool.

I ended up with this:

Just using the built-in formatting options means we could create something that was much easier on the eye. It has a few other improvements too:

The heading is now a link to the PR, which is obviously useful.

I moved the “build” section earlier - because if the build is failing, users probably won’t need to re-review the PR yet. An example of failing users faster.

Using the “short” format for fields lets it make better use of the horizontal space.

In the abstract, I think this is pretty decent now. The next step would be user testing - seeing whether we’re actually including the right information here, and checking which bits matter the most to users.

[uiwriting]

A nice piece of help for Instagram Stories

I came across this the other day when looking at Stories on Instagram (photos that play like a slideshow, and only last 24 hours). Stories take up the whole of your screen, and don’t have any obvious controls, so it can be a bit hard to work out what you can do, apart from sit there and watch the photos progress.

And there are actually a bunch of gestures you can use to interact with them - which, like many gesture-based controls, are very hard to discover.

So when this screen popped up when I opened a story the other day, I really appreciated it.

Why is this good help?

It’s at the point of need: I can see this and then immediately try out the features.

It combines visuals and text for clearer explanations: it’s not always obvious what the words used to describe gestures mean, so this reinforces the meaning.

It’s short and sweet: uses simple language and clear descriptions.

Any problems?

There’s no way to come back to this help - that I could see, anyway. Once you’ve tapped away, it’s gone. So you have to remember what you see on this screen.

So this screen helps a bit with the discoverability problem - but it’s a one-time intervention that doesn’t solve it entirely. 

[uiwriting]

Writing can’t fix bad design

This door from a train toilet is a great example of adding lots of information in an attempt to fix bad UI design.

What’s wrong with this design?

Usually, the way you interact with a door is signalled by cues on the door itself - for example a handle to open it, a bolt to shut. When these perceived affordances of how to use a door are obvious, you don’t need to add any words to explain how to use it. (Of course, badly designed doors are everywhere.)

For this door, instead of interacting with the door itself, you interact with these buttons. They’re labelled badly with unclear icons. (Icons are almost never as clear as you think they are, but that’s a rant for another day.)

You can tell they’re bad because the design had to add words *on top of* the icons to explain what they mean. And then also arrows next to the words, because the labels were badly placed, making it unclear which button the labels were for.

But even that isn’t enough to explain how to use this door.

The design itself communicates poorly

When you push the “Close” button, it’s not obvious that you need to do something else as well in order for the door to lock. (Which is reasonably important in a toilet door.)

You can tell this has been a problem  -  there are three separate places where extra text asks you not to forget to push the “Lock” button. There’s piles of information around this design, trying to help people to use it successfully.

Telling isn’t the right solution

The door design fails to make it obvious what its users need to do, and adding signs off to the side doesn’t help. Many won’t notice the signs because it’s not where their attention is at the time  -  they literally won’t see the text telling them what to do.

What’s needed is a design that guides users towards what they need to do, or even better, does it for them. It needs obvious signalling. Clear communication. Understanding of how people behave, and anticipation of what they’ll do.

When the problem is “people aren’t using this design as intended”, the solution isn’t “tell them to use it properly”. It’s “make a better design”.

[uiwriting]

A nice, simple login page

A page for logging in isn’t a complex idea, but often they’re overdone, overcomplicated, or confusing. So I wanted to call out a nice example with decent writing, from Trello:

Good things here:

A clear title, reminding you where you are and what’s happening.

Straightforward labels. Looking out for users who want to log in with a username, not an email. 

Good placeholder text reinforcing what goes in the fields. But it keeps labels outside the field too, so users don’t have to rely on it.

A clear, primary call to action. (I wish they’d used sentence case, ie “Log in”, but you can’t have everything!)

The secondary options are still here, obvious but unobtrusive. They’re cleanly and concisely phrased, targeting users with questions and giving them clearly phrased actions to follow up with.

I also liked the error message I got when I tried to log in:

For me, it’s a great example along the lines of the Voice & Tone guidelines on errors: it’s calm, serious and straightforward, and offers a next step. It shows you don’t need to be formal, stuffy or alarming in error messages. And actually, I’d argue that a conversational (if serious) tone here is exactly what a user needs in an error case.

I like the contents of the message: the information it gave me about what was wrong guided me towards what I needed to do next, and helped me understand. Not everyone agrees, and it’s true that it goes into possibly unnecessary detail about the implementation of Google account authentication.

An alternative, rephrasing the detail so it’s relevant to the user, is “You signed up with a Google Account, so you can’t log in with a password. Try using the Log in with Google button.” 

What would be super nice is if the message itself contained a link to the ‘Log in with Google’ page - so you don’t have to look around the page to find the link. But as the page is so minimal, it’s not too much of a problem.

[uiwriting]

How human do you want your chatbot to be?

I’ve seen a few examples recently of people frustrated with chatbots that just don’t understand what they’re trying to say. 

Because a chatbot’s UI is conversational, people building them want their bots to be bursting with personality - and to seem like real people. Conversation gives the illusion of humanity: it makes users feel like they can speak and be understood. But the more your users feel like they’re talking to a human, the more they’ll talk like they talk to other humans. 

And that’s a problem for bots. Most of them have a very limited range of what input they can understand, and aren’t very tolerant of variation:

My CNN bot already feels a little bit spammy. Cute emoticons don't really cut it in this case... pic.twitter.com/9EY7gBwyMQ

— Olivia Solon (@oliviasolon)

April 13, 2016

Natural language processing needs some work. pic.twitter.com/Sbm6HqKyq1

— Benedict Evans (@BenedictEvans)

April 14, 2016

It turns out the secret is to say "unusubscribe", but nothing else. That's a discoverability problem. The great advantage of a graphical (rather than conversational) user interface is that users can see what’s possible. To replicate this with a bot, you would need a list of options - sort of like a call centre. “Press 1 for today’s forecast, 2 for tomorrow’s, or press 3 to unsubscribe.”

Now, a bot like that doesn’t give you the illusion of humanity. What it does give you are decent odds of user success. Even if your user doesn’t reply “1″, and instead says “Today’s forecast”, you’ve given them language that they’re likely to mirror - language you can add to your list of things your bot recognises. 

In the CNN example, the bot had an unsubscribe feature - it just didn’t tell users that it existed, or how they could access it. Bots need to communicate their capabilities - and their limitations. It’s a trade-off between conciseness and usability, and between perceived humanity and user success.

To try to help, you can:

remind your users that they're talking to a bot, not a person

tell your users what the bot can (and can't) do

give your users the language you want them to use, to make them more likely to say things your bot can understand

If you're building a conversational UI, consider: do you want your bot to come across as human? Or do you just want to help your users get stuff done?

Other posts I thought were interesting:

Dan Grover on the limits of conversational UIs

Amy Thibodeau on other reasons to be careful about adding lots of personality