Successfully reported this slideshow.
Your SlideShare is downloading. ×

Before the docs: writing for user interfaces

Before the docs: writing for user interfaces

Download to read offline

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/

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/

More Related Content

Before the docs: writing for user interfaces

  1. Before the docs Writing for user interfaces Beth Aitman @baitman
  2. Why does UI text matter? Introduction - Microcopy - Help - Errors
  3. Why does UI text matter? The UI comes first. Introduction - Microcopy - Help - Errors
  4. Introduction - Microcopy - Help - Errors
  5. Introduction - Microcopy - Help - Errors
  6. Introduction - Microcopy - Help - Errors
  7. It’s not one or the other Introduction - Microcopy - Help - Errors
  8. It’s not one or the other Docs and UI support each other. Introduction - Microcopy - Help - Errors
  9. Three main areas 1. Microcopy 2. Embedded help 3. Error messages Introduction - Microcopy - Help - Errors
  10. Introduction - Microcopy - Help - Errors
  11. Introduction - Microcopy - Help - Errors
  12. Introduction - Microcopy - Help - Errors
  13. First, microcopy Introduction - Microcopy - Help - Errors
  14. Introduction - Microcopy - Help - Errors
  15. Introduction - Microcopy - Help - Errors
  16. Text makes UIs meaningful from https://signalvnoise.com/posts/3404-reminder-design-is-still-about-words 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. Microcopy is difficult “Naming things is hard!” Introduction - Microcopy - Help - Errors
  19. 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. Three strategies for microcopy 1. Think from the user perspective 2. Choose names they can understand 3. Experiment with phrasing Introduction - Microcopy - Help - Errors
  27. 1. Think from the user perspective Explain what a feature does, not how it works Introduction - Microcopy - Help - Errors
  28. Introduction - Microcopy - Help - Errors
  29. For buttons, think actions Introduction - Microcopy - Help - Errors
  30. Not this! For buttons, think actions Introduction - Microcopy - Help - Errors
  31. 2. What’s it normally called? What do users call it? What will they understand? Introduction - Microcopy - Help - Errors
  32. Introduction - Microcopy - Help - Errors
  33. Introduction - Microcopy - Help - Errors
  34. Introduction - Microcopy - Help - Errors
  35. Introduction - Microcopy - Help - Errors
  36. 3. Experiment with phrasing Introduction - Microcopy - Help - Errors
  37. 3. Experiment with phrasing Try explaining it in a sentence. Introduction - Microcopy - Help - Errors
  38. Introduction - Microcopy - Help - Errors
  39. Introduction - Microcopy - Help - Errors
  40. … and embedded help is there if you need it. Introduction - Microcopy - Help - Errors
  41. Introduction - Microcopy - Help - Errors
  42. Introduction - Microcopy - Help - Errors
  43. Introduction - Microcopy - Help - Errors
  44. Embedded help Introduction - Microcopy - Help - Errors
  45. Introduction - Microcopy - Help - Errors
  46. Introduction - Microcopy - Help - Errors
  47. Introduction - Microcopy - Help - Errors
  48. Embedded help - What do you include? - When do you use docs? - Where do you put help? - Styles Introduction - Microcopy - Help - Errors
  49. What goes in embedded help? “What does your user need to know to complete their task?” Introduction - Microcopy - Help - Errors
  50. 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. Don’t overload people Introduction - Microcopy - Help - Errors
  56. 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
  57. Show it in the relevant place Introduction - Microcopy - Help - Errors
  58. Introduction - Microcopy - Help - Errors
  59. Introduction - Microcopy - Help - Errors
  60. Embedded help styles There are tons. Introduction - Microcopy - Help - Errors
  61. Embedded help styles There are tons. But I like: - inline help Introduction - Microcopy - Help - Errors
  62. Embedded help styles There are tons. But I like: - expandable questions Introduction - Microcopy - Help - Errors
  63. Embedded help styles There are tons. But I like: - hover text Introduction - Microcopy - Help - Errors
  64. Embedded help styles There are tons. So experiment! Introduction - Microcopy - Help - Errors
  65. 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
  66. Error messages Introduction - Microcopy - Help - Errors
  67. Error messages are easy! I’ve got a formula. Introduction - Microcopy - Help - Errors
  68. - what went wrong - consequences - how to fix it Introduction - Microcopy - Help - Errors
  69. - what went wrong - consequences - how to fix it Introduction - Microcopy - Help - Errors
  70. Introduction - Microcopy - Help - Errors
  71. Introduction - Microcopy - Help - Errors
  72. Introduction - Microcopy - Help - Errors
  73. - what went wrong - consequences - how to fix it Introduction - Microcopy - Help - Errors
  74. Introduction - Microcopy - Help - Errors
  75. Introduction - Microcopy - Help - Errors
  76. - what went wrong - consequences - how to fix it Introduction - Microcopy - Help - Errors
  77. Introduction - Microcopy - Help - Errors
  78. Introduction - Microcopy - Help - Errors
  79. Introduction - Microcopy - Help - Errors
  80. Introduction - Microcopy - Help - Errors
  81. - what went wrong - consequences - how to fix it (and leave it out if it doesn’t apply) Introduction - Microcopy - Help - Errors
  82. 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
  83. One last thing! uiwriting.tumblr.com @baitman
  84. Thanks for listening :) If you have questions/opinions, talk to me after, or get in touch! uiwriting.tumblr.com @baitman

×