Embedded User Assistance: Third Rail or Third Way?

Embedded User Assistance:Third Rail or Third Way?

Steven JongSTC New England InterChange Conference

April 2016

NO TRESPASSINGDANGER THIRD RAIL

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

@DangerfieldSez

Steven Jong, InterChange 2016 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


Do GUIs really need words?(Tom Johnson)

2 April 2016

http://idratherbewriting.com/2010/08/11/the-interface-is-text-organizing-content-23/


Traditional: Help window

2 April 2016

Eclipse Foundation


Traditional: Context-sensitive help

2 April 2016

http://www.ibm.com/developerworks/library/j-javahelp2/


PRESENTING TRADITIONAL DOCUMENTS IN NEW WAYS

2 April 2016From http://www.vintage-computer.com/ibm_pc.shtmls


New: New-features guide

2 April 2016

From “Web UI elements,” by Rebecca Reynolds, Pinterest.com


New: Getting started guide

2 April 2016


EMBEDDING ASSISTANCE

2 April 2016


What is embedded assistance?Textual and graphical elements that users encounter in HW and SW products8. Embedded help panes7. Wizards6. Hover help5. Tooltips4. Messages3. Inline text2. Field input hints1. UI labels

2 April 2016

Developing Quality Technical Information, 3rd Ed.


Embedded Help panes

2 April 2016


Wizards

2 April 2016


Multi-step wizard with train

2 April 2016

Courtesy Oracle


Hover help

2 April 2016

Courtesy Oracle


Tooltips

2 April 2016

Courtesy Oracle


Tooltip with progressive disclosure

2 April 2016

Courtesy Autodesk


Tooltip with progressive disclosure (continued)

2 April 2016

Courtesy Autodesk


Messages

2 April 2016

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


Moving messages closer to the source

2 April 2016

Courtesy Oracle


Improving an error message

2 April 2016

Courtesy Autodesk


Adding images to text

2 April 2016

Courtesy Autodesk


Animating a hint

2 April 2016

Courtesy Oracle


Inline text

2 April 2016

Courtesy Autodesk


Inline text—how much?

2 April 2016


Field input hints

2 April 2016


UI labels

2 April 2016

From Microsoft Developer Network Library, “User Interface Text”


Improving a label

2 April 2016

Courtesy Autodesk


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

Amazon.com


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


DQTI: “The tech writer’s role today”

DQTI advocates:• Know the user stories• Be the user’s advocate• Own the words

2 April 2016

Image courtesy of nenetus at FreeDigitalPhotos.net


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

Chris Whiton, NH Magazine


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


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


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


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

Amazon.com


20 guiding principles for experience design (Whitney Hess, 2009)

1. Stay out of people’s way2. Present few choices3. Limit distractions4. Group related objects5. Create a visual hierarchy

matching user’s need6. Provide strong information

scent7. Provide signposts and cues8. Provide context9. Avoid jargon

10. Make things efficient11. Use appropriate defaults12. Use constraints appropriately13. Make actions reversible14. Reduce latency15. Provide feedback16. Use emotion17. Less is more18. Be consistent19. Make a good first impression20. Be credible and trustworthy

2 April 2016

https://whitneyhess.com/blog/2009/11/23/so-you-wanna-be-a-user-experience-designer-step-2-guiding-principles/


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

http://www.igorpurlantov.net/top-ways-to-know-if-your-cat-is-happy-igor-purlantov/


Is this still technical communication?

Working with wordsExplaining technical information to usersFollowing rules we already knowUsing principles of layout and formatImproved by style guidesMaking the complex clear

2 April 2016


Example: Progressive disclosure applied to embedded assistance

1. UI labels2. Messages3. Static text for windows4. Static text for fields5. Hover help6. Window help7. Online help

2 April 2016


Message example: What to say?

2 April 2016

Courtesy Oracle


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

ImgStocks.com


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


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

Patty Gale


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/UserExperience/Conceptual/OSXHIGuidelines/TerminologyWording.html#//apple_ref/doc/uid/20000957-CH15-SW1

2 April 2016

http://www.nngroup.com/articles/

https://msdn.microsoft.com/en-us/library/dn742478.aspx


Questions?

2 April 2016


Messages and actions

2 April 2016

From Microsoft Developer Network Library, “User Interface Text”


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

Courtesy Oracle

Embedded User Assistance: Third Rail or Third Way?

Technology