1.
Embedded User Assistance:
Third Rail or Third Way?
Steven Jong
STC New England InterChange Conference
April 2016

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.
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.
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.
Traditional: Help window
2 April 2016 Steven Jong, InterChange 2016 5
Eclipse Foundation

6.
Traditional: Context-sensitive help
2 April 2016 Steven Jong, InterChange 2016 6
http://www.ibm.com/developerworks/library/j-javahelp2/

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.
New: New-features guide
2 April 2016 Steven Jong, InterChange 2016 8
From “Web UI elements,” by Rebecca Reynolds, Pinterest.com

9.
New: Getting started guide
2 April 2016 Steven Jong, InterChange 2016 9

10.
EMBEDDING ASSISTANCE
2 April 2016 Steven Jong, InterChange 2016 10

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.
Embedded Help panes
2 April 2016 Steven Jong, InterChange 2016 12

13.
Wizards
2 April 2016 Steven Jong, InterChange 2016 13

14.
Multi-step wizard with train
2 April 2016 Steven Jong, InterChange 2016 14
Courtesy Oracle

15.
Hover help
2 April 2016 Steven Jong, InterChange 2016 15
Courtesy Oracle

16.
Tooltips
2 April 2016 Steven Jong, InterChange 2016 16
Courtesy Oracle

17.
Tooltip with progressive disclosure
2 April 2016 Steven Jong, InterChange 2016 17
Courtesy Autodesk

18.
Tooltip with progressive disclosure
(continued)
2 April 2016 Steven Jong, InterChange 2016 18
Courtesy Autodesk

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.
Moving messages closer to the source
2 April 2016 Steven Jong, InterChange 2016 20
Courtesy Oracle

21.
Improving an error message
2 April 2016 Steven Jong, InterChange 2016 21
Courtesy Autodesk

22.
Adding images to text
2 April 2016 Steven Jong, InterChange 2016 22
Courtesy Autodesk

23.
Animating a hint
2 April 2016 Steven Jong, InterChange 2016 23
Courtesy Oracle

24.
Inline text
2 April 2016 Steven Jong, InterChange 2016 24
Courtesy Autodesk

25.
Inline text—how much?
2 April 2016 Steven Jong, InterChange 2016 25

26.
Field input hints
2 April 2016 Steven Jong, InterChange 2016 26

27.
UI labels
2 April 2016 Steven Jong, InterChange 2016 27
From Microsoft Developer Network Library, “User Interface Text”

28.
Improving a label
2 April 2016 Steven Jong, InterChange 2016 28
Courtesy Autodesk

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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Message example: What to say?
2 April 2016 Steven Jong, InterChange 2016 41
Courtesy Oracle

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.
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.
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.
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.
Questions?
2 April 2016 Steven Jong, InterChange 2016 46

47.
Messages and actions
2 April 2016 Steven Jong, InterChange 2016 48
From Microsoft Developer Network Library, “User Interface Text”

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