Given at Write the Docs Europe, 2015. See the write-up here (https://docs.google.com/document/d/1HTuKl4gSOcqdqYY72MK_frbTpHb73j_WnZN3HExp184/edit?usp=sharing) Good documentation is important, but it should be your last resort. You need to help users before they reach the docs - in the user interface itself. In this talk, I discuss: - strategies for writing microcopy when you’re short on space - what to explain in the UI, and what to save for the documentation - how to pick the right style of embedded help - what makes a great error message (and a terrible one) ... with plenty of real-world examples of doing it right and wrong. If you're interested in this, see my blog for more detailed examples: http://uiwriting.tumblr.com/

1. Before the docs
Writing for user interfaces
Beth Aitman
@baitman

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

4. Why does UI text matter?
The UI comes first.
Introduction - Microcopy - Help - Errors

5. Introduction - Microcopy - Help - Errors

6. Introduction - Microcopy - Help - Errors

7. Introduction - Microcopy - Help - Errors

8. It’s not one or the other
Introduction - Microcopy - Help - Errors

9. It’s not one or the other
Docs and UI support each other.
Introduction - Microcopy - Help - Errors

10. Three main areas
1. Microcopy
2. Embedded help
3. Error messages
Introduction - Microcopy - Help - Errors

11. Introduction - Microcopy - Help - Errors

12. Introduction - Microcopy - Help - Errors

13. Introduction - Microcopy - Help - Errors

14. First, microcopy
Introduction - Microcopy - Help - Errors

15. Introduction - Microcopy - Help - Errors

16. Introduction - Microcopy - Help - Errors

17. Text makes UIs meaningful
from https://signalvnoise.com/posts/3404-reminder-design-is-still-about-words
Introduction - Microcopy - Help - Errors

18. Text makes UIs meaningful
from https://signalvnoise.com/posts/3404-reminder-design-is-still-about-words
Introduction - Microcopy - Help - Errors

19. Microcopy is difficult
“Naming things is hard!”
Introduction - Microcopy - Help - Errors

20. Introduction - Microcopy - Help - Errors

21. Introduction - Microcopy - Help - Errors

22. Introduction - Microcopy - Help - Errors

23. Introduction - Microcopy - Help - Errors

24. Introduction - Microcopy - Help - Errors

25. Introduction - Microcopy - Help - Errors

26. Introduction - Microcopy - Help - Errors

27. Three strategies for microcopy
1. Think from the user perspective
2. Choose names they can understand
3. Experiment with phrasing
Introduction - Microcopy - Help - Errors

28. 1. Think from the user perspective
Explain what a feature does, not how it
works
Introduction - Microcopy - Help - Errors

29. Introduction - Microcopy - Help - Errors

30. For buttons, think actions
Introduction - Microcopy - Help - Errors

31. Not this!
For buttons, think actions
Introduction - Microcopy - Help - Errors

32. 2. What’s it normally called?
What do users call it?
What will they understand?
Introduction - Microcopy - Help - Errors

33. Introduction - Microcopy - Help - Errors

34. Introduction - Microcopy - Help - Errors

35. Introduction - Microcopy - Help - Errors

36. Introduction - Microcopy - Help - Errors

37. 3. Experiment with phrasing
Introduction - Microcopy - Help - Errors

38. 3. Experiment with phrasing
Try explaining it in a sentence.
Introduction - Microcopy - Help - Errors

39. Introduction - Microcopy - Help - Errors

40. Introduction - Microcopy - Help - Errors

41. … and embedded help is there if you need
it.
Introduction - Microcopy - Help - Errors

42. Introduction - Microcopy - Help - Errors

43. Introduction - Microcopy - Help - Errors

44. Introduction - Microcopy - Help - Errors

45. Embedded help
Introduction - Microcopy - Help - Errors

46. Introduction - Microcopy - Help - Errors

47. Introduction - Microcopy - Help - Errors

48. Introduction - Microcopy - Help - Errors

49. Embedded help
- What do you include?
- When do you use docs?
- Where do you put help?
- Styles
Introduction - Microcopy - Help - Errors

50. What goes in embedded help?
“What does your user need to know to
complete their task?”
Introduction - Microcopy - Help - Errors

51. Introduction - Microcopy - Help - Errors

52. Introduction - Microcopy - Help - Errors

53. Introduction - Microcopy - Help - Errors

54. Introduction - Microcopy - Help - Errors

55. Introduction - Microcopy - Help - Errors

56. Don’t overload people
Introduction - Microcopy - Help - Errors

57. 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

58. Show it in the relevant place
Introduction - Microcopy - Help - Errors

59. Introduction - Microcopy - Help - Errors

60. Introduction - Microcopy - Help - Errors

61. Embedded help styles
There are tons.
Introduction - Microcopy - Help - Errors

62. Embedded help styles
There are tons. But I like:
- inline help
Introduction - Microcopy - Help - Errors

63. Embedded help styles
There are tons. But I like:
- expandable questions
Introduction - Microcopy - Help - Errors

64. Embedded help styles
There are tons. But I like:
- hover text
Introduction - Microcopy - Help - Errors

65. Embedded help styles
There are tons.
So experiment!
Introduction - Microcopy - Help - Errors

66. 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

67. Error messages
Introduction - Microcopy - Help - Errors

68. Error messages are easy!
I’ve got a formula.
Introduction - Microcopy - Help - Errors

69. - what went wrong
- consequences
- how to fix it
Introduction - Microcopy - Help - Errors

70. - what went wrong
- consequences
- how to fix it
Introduction - Microcopy - Help - Errors

71. Introduction - Microcopy - Help - Errors

72. Introduction - Microcopy - Help - Errors

73. Introduction - Microcopy - Help - Errors

74. - what went wrong
- consequences
- how to fix it
Introduction - Microcopy - Help - Errors

75. Introduction - Microcopy - Help - Errors

76. Introduction - Microcopy - Help - Errors

77. - what went wrong
- consequences
- how to fix it
Introduction - Microcopy - Help - Errors

78. Introduction - Microcopy - Help - Errors

79. Introduction - Microcopy - Help - Errors

80. Introduction - Microcopy - Help - Errors

81. Introduction - Microcopy - Help - Errors

82. - what went wrong
- consequences
- how to fix it
(and leave it out if it doesn’t apply)
Introduction - Microcopy - Help - Errors

83. 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

84. One last thing!
uiwriting.tumblr.com
@baitman

85. Thanks for listening :)
If you have questions/opinions, talk to me after, or get in touch!
uiwriting.tumblr.com
@baitman