Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Embedded User Assistance: Third Rail or Third Way?

1,560 views

Published on

It’s challenging to provide technical documentation in an environment where people say “nobody reads the manual” (or even “nobody looks at the help”) and instead demand “intuitive interfaces.” Smartphones are now the most common web browser, and we face an audience with little patience for reading; we feel squeezed out of existence. But there’s an opportunity for us to go from a supporting, or even superfluous, role to center stage: by providing embedded user assistance.

Steve describes and gives examples of embedded assistance, shows how it’s being used today, discuses the challenges of working close to or even inside the code, and relates the effects of participating throughout the design process (as in an Agile environment) as well as working with UX designers (or becoming one yourself).

Presentation given at STC New England InterChange Conference, 2 April 2016, Lowell, Massachusetts USA.

Published in: Technology

Embedded User Assistance: Third Rail or Third Way?

  1. 1. Embedded User Assistance: Third Rail or Third Way? Steven Jong STC New England InterChange Conference April 2016
  2. 2. Just between us… • Nielsen’s First Law of computer docs: “people don’t read it” • Limited space available on mobile platforms • “Over the wall” development • Competitive environment for info 2 April 2016 Steven Jong, InterChange 2016 2 @DangerfieldSez
  3. 3. Everything is changing… almost • User interfaces are changing • Technical information types are changing • Development methodologies are changing • User issues are not 2 April 2016 Steven Jong, InterChange 2016 3
  4. 4. Do GUIs really need words? (Tom Johnson) 2 April 2016 Steven Jong, InterChange 2016 4 http://idratherbewriting.com/2010/08/11/the-interface-is-text-organizing-content-23/
  5. 5. Traditional: Help window 2 April 2016 Steven Jong, InterChange 2016 5 Eclipse Foundation
  6. 6. Traditional: Context-sensitive help 2 April 2016 Steven Jong, InterChange 2016 6 http://www.ibm.com/developerworks/library/j-javahelp2/
  7. 7. PRESENTING TRADITIONAL DOCUMENTS IN NEW WAYS 2 April 2016 Steven Jong, InterChange 2016 7 From http://www.vintage-computer.com/ibm_pc.shtmls
  8. 8. New: New-features guide 2 April 2016 Steven Jong, InterChange 2016 8 From “Web UI elements,” by Rebecca Reynolds, Pinterest.com
  9. 9. New: Getting started guide 2 April 2016 Steven Jong, InterChange 2016 9
  10. 10. EMBEDDING ASSISTANCE 2 April 2016 Steven Jong, InterChange 2016 10
  11. 11. What is embedded assistance? Textual and graphical elements that users encounter in HW and SW products 8. Embedded help panes 7. Wizards 6. Hover help 5. Tooltips 4. Messages 3. Inline text 2. Field input hints 1. UI labels 2 April 2016 Steven Jong, InterChange 2016 11 Developing Quality Technical Information, 3rd Ed.
  12. 12. Embedded Help panes 2 April 2016 Steven Jong, InterChange 2016 12
  13. 13. Wizards 2 April 2016 Steven Jong, InterChange 2016 13
  14. 14. Multi-step wizard with train 2 April 2016 Steven Jong, InterChange 2016 14 Courtesy Oracle
  15. 15. Hover help 2 April 2016 Steven Jong, InterChange 2016 15 Courtesy Oracle
  16. 16. Tooltips 2 April 2016 Steven Jong, InterChange 2016 16 Courtesy Oracle
  17. 17. Tooltip with progressive disclosure 2 April 2016 Steven Jong, InterChange 2016 17 Courtesy Autodesk
  18. 18. Tooltip with progressive disclosure (continued) 2 April 2016 Steven Jong, InterChange 2016 18 Courtesy Autodesk
  19. 19. Messages 2 April 2016 Steven Jong, InterChange 2016 19 From “Error Messages: The Good, the Bad, and the Ugly,” G. D. Warner, MacTech 17(12), 2001, http://www.mactech.com/articles/mactech/Vol.17/17.12/Dec01CoverStory/index.html
  20. 20. Moving messages closer to the source 2 April 2016 Steven Jong, InterChange 2016 20 Courtesy Oracle
  21. 21. Improving an error message 2 April 2016 Steven Jong, InterChange 2016 21 Courtesy Autodesk
  22. 22. Adding images to text 2 April 2016 Steven Jong, InterChange 2016 22 Courtesy Autodesk
  23. 23. Animating a hint 2 April 2016 Steven Jong, InterChange 2016 23 Courtesy Oracle
  24. 24. Inline text 2 April 2016 Steven Jong, InterChange 2016 24 Courtesy Autodesk
  25. 25. Inline text—how much? 2 April 2016 Steven Jong, InterChange 2016 25
  26. 26. Field input hints 2 April 2016 Steven Jong, InterChange 2016 26
  27. 27. UI labels 2 April 2016 Steven Jong, InterChange 2016 27 From Microsoft Developer Network Library, “User Interface Text”
  28. 28. Improving a label 2 April 2016 Steven Jong, InterChange 2016 28 Courtesy Autodesk
  29. 29. Developing Quality Technical Information, 3rd Edition “[W]e organized [this book] to show you how to apply quality characteristics that make technical information, including information embedded in user interfaces, easy to use, easy to understand, and easy to find.” 2 April 2016 Steven Jong, InterChange 2016 29 Amazon.com
  30. 30. DQTI: “Technical information continues to evolve” “The nature of our work as technical communicators continues to change, more rapidly than ever.” • “Some of us began our careers delivering camera- ready copy for a shelf of physical books” • “[W]ith the advent of the web, we used our online help-writing skills to rework books into online topic-based documentation” • “Now we need to expand our focus beyond topic- based information and onto the product user interfaces themselves” 2 April 2016 Steven Jong, InterChange 2016 30
  31. 31. DQTI: “The tech writer’s role today” DQTI advocates: • Know the user stories • Be the user’s advocate • Own the words 2 April 2016 Steven Jong, InterChange 2016 31 Image courtesy of nenetus at FreeDigitalPhotos.net
  32. 32. Comparing development methodologies Waterfall • Specifications • Develop first, then document • Fewer, longer cycles • GUI suggestions are annoyances Agile • Integrated team • If at first you don’t succeed, try, try again • More, faster cycles • GUI suggestions are welcomed 2 April 2016 Steven Jong, InterChange 2016 32 Chris Whiton, NH Magazine
  33. 33. Third rail? • This is software development—we are writing code • Our tools won’t work • Breaks 1 topic/page model • No archiving, sharing, or reuse • Agile = scrap and rework • Will they accept our edits? • Lots of never-ending work 2 April 2016 Steven Jong, InterChange 2016 33
  34. 34. Sample source code (JavaScript) common: { filter: "Filter", filterPlaceholder: "Filter Existing Items", filterTitle: "Enter Filter Term", filterButtonHelp: "Click to filter existing items", deleteWarning: "Warning, this will permanently delete the object(s) from the server, continue?" }, dif: { difObjects: "Compare Two {0}", fieldName: "Field Name", selectFirstObject: "Select First {0}", selectSecondObject: "Select Second {0}", filterDifResults:"Only Show Differences“ } }, 2 April 2016 Steven Jong, InterChange 2016 34
  35. 35. Sample source code (XML) <?xml version="1.0" encoding="UTF-8" ?> <xliff version="1.1" xmlns="urn:oasis:names:tc:xliff:document:1.1"> <file source-language="en" original="this" datatype="xml"> <body> <trans-unit id="MYCUSTHELP_NEWHELPTOPIC_DEFINITION"> <source>Credit Card Definition</source> <target/> <note>This is the credit card definition text.</note> </trans-unit> <trans-unit id="MYCUSTHELP_NEWTOPIC2_INSTRUCTIONS"> <source>Credit Card Instructions</source> <target/> <note>This is the credit card instruction text.</note> </trans-unit> </body> </file> </xliff> 2 April 2016 Steven Jong, InterChange 2016 35
  36. 36. Don’t Make Me Think, Revisited • Usability + Information Architecture = Usability Experience (UX) • Core UX principles sound familiar • UX professionals and tech communicators share overlapping skill sets 2 April 2016 Steven Jong, InterChange 2016 36 Amazon.com
  37. 37. 20 guiding principles for experience design (Whitney Hess, 2009) 1. Stay out of people’s way 2. Present few choices 3. Limit distractions 4. Group related objects 5. Create a visual hierarchy matching user’s need 6. Provide strong information scent 7. Provide signposts and cues 8. Provide context 9. Avoid jargon 10. Make things efficient 11. Use appropriate defaults 12. Use constraints appropriately 13. Make actions reversible 14. Reduce latency 15. Provide feedback 16. Use emotion 17. Less is more 18. Be consistent 19. Make a good first impression 20. Be credible and trustworthy 2 April 2016 Steven Jong, InterChange 2016 37 https://whitneyhess.com/blog/2009/11/23/so-you-wanna-be-a-user-experience-designer-step-2-guiding-principles/
  38. 38. Third way? • All users rely on GUI words • Work in GUI to sidestep formatting into Help • Provide rich, appropriate content • We can fit within Agile methodology • Provide direct value • Focus on what’s important to users • Shortage of UX experts • Agile affords incremental opportunities to improve 2 April 2016 Steven Jong, InterChange 2016 38 http://www.igorpurlantov.net/top-ways-to-know-if- your-cat-is-happy-igor-purlantov/
  39. 39. Is this still technical communication? Working with words Explaining technical information to users Following rules we already know Using principles of layout and format Improved by style guides Making the complex clear 2 April 2016 Steven Jong, InterChange 2016 39
  40. 40. Example: Progressive disclosure applied to embedded assistance 1. UI labels 2. Messages 3. Static text for windows 4. Static text for fields 5. Hover help 6. Window help 7. Online help 2 April 2016 Steven Jong, InterChange 2016 40
  41. 41. Message example: What to say? 2 April 2016 Steven Jong, InterChange 2016 41 Courtesy Oracle
  42. 42. Issues • Doing different things, or more things? • Who controls the work? • What tools to use? • What functions to doc? • Which types to use? • What to write? • Archive/share/reuse? • What if you’re confused by the GUI? • Simple is hard 2 April 2016 Steven Jong, InterChange 2016 42 ImgStocks.com
  43. 43. Summary • Everyone uses the GUI, so own the words • Understand embedded assistance for applications on desktop, Web, and mobile • Apply new presentation forms when they help users • Embrace Agile if you get the chance • Work with UX—be UX • It’s still technical communication 2 April 2016 Steven Jong, InterChange 2016 43
  44. 44. Special thanks… I’m grateful to Patty Gale, Learning Content Developer at Autodesk, for kindly sharing examples of embedded assistance created by her company 2 April 2016 Steven Jong, InterChange 2016 44 Patty Gale
  45. 45. For more information… • Developing Quality Technical Information: A Handbook for Writers and Editors, Third Edition. Michelle Carey et al. IBM Press, 2014 • Don’t Make Me Think, Revisited. Steve Krug. New Riders, 2014 • Nielsen Norman Group (UX articles), www.nngroup.com/articles/ • User interface text guidelines: – Microsoft: https://msdn.microsoft.com/en- us/library/dn742478.aspx – Apple: https://developer.apple.com/library/mac/documentation/UserE xperience/Conceptual/OSXHIGuidelines/TerminologyWording.ht ml#//apple_ref/doc/uid/20000957-CH15-SW1 2 April 2016 Steven Jong, InterChange 2016 45
  46. 46. Questions? 2 April 2016 Steven Jong, InterChange 2016 46
  47. 47. Messages and actions 2 April 2016 Steven Jong, InterChange 2016 48 From Microsoft Developer Network Library, “User Interface Text”
  48. 48. Tooltip example: What should we say? Applying audience analysis and progressive disclosure, what should this tooltip say? Should we provide any further help, and if so, what? How should we display it? Note: There can be two sites 2 April 2016 Steven Jong, InterChange 2016 49 Courtesy Oracle

×