-
-
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
I know this is the last session, and I thank you for choosing to spend it with me
I will try to make it worth your while
For the purposes of this presentation, I have almost 40 years of technical writing experience, in companies large and small, starting with printed manuals
I will present examples of embedded user assistance from my employer, Oracle, as well as from Apple, Microsoft, Autodesk, and other companies
You don’t have to take notes
My slides and notes will be posted on SlideShare.net after the conference
To paraphrase Rodney Dangerfield, I’m OK now, but a while ago I was in rough shape…
(Are we alone? I’m going to show you some objectionable material…)
=/=
Jakob Nielsen (who founded Nielsen Norman with Don Norman) said people don’t read computers docs
I’ve always considered this a slur on our profession, but coming from Nielsen it’s not an opinion, it’s a research finding. And he’s not done:
“This finding is even stronger for websites, where users truly shy away from any reading that is not essential to their task. Click on Help? Never. Users read system documentation only when they are in trouble.” (That's his Second Law)
(Nielson’s First Law: https://www.nngroup.com/articles/error-message-guidelines/)
I’ve read of studies that conclude that users are afraid to ask for help in any form
Some developers even deny the need for help. Stop me if you’re heard this one before:
“The experience [of using mobile apps] is supposed to be so compelling, and so intuitive, that the user will naturally flow through it without any need for assistance. Adding help is … an admission of design failure.”
(http://venturebeat.com/2013/09/21/90-of-mobile-apps-have-inadequate-help/)
=/=
The low usage of Help for apps and websites is bad enough
But since 2007 (iPhone), smartphones have become the #1 web browser on the Internet (from novelty to target platform in less than ten years)
The screen real estate on smartphones is sharply limited
You’ve heard people at this conference talk about adapting help to mobile
But trying to fit our books-in-Help on a smartphone screen is like balancing a plate and cup at a party—awkward
Millennials are now the largest cohort in the population and workforce
They have no idea how cleverly we’ve given them the books we’ve always provided; they just say “what is this?” and ignore it
=/=
In many shops, the product doesn’t resemble the spec
By the time we get the product, the engineers have already moved on to the next release
Development is triaging bugs, so “edits” are often summarily deferred
Stop me if you’ve heard this one before: “I have three blocking bugs to fix. Do you want me to make the product work, or stop to fix a label?”
By the time we spot problems with the GUI, we can only clean up the errors:
At the end of the day, we're really janitors. I know it may sound derogatory and even offensive, but our job is to clean up other people's messes. Project managers don't want to see us, they don't want to interact with us. They just want us to arrive after the work is done; they want us to come in and do our jobs quietly, cleaning up the spills, vacuuming the crumbs, taking out the trash—all without complaint or objection.
(quoted in “The Interface is Text,” Tom Johnson, I’d Rather Be Writing blog (http://idratherbewriting.com/2010/08/11/the-interface-is-text-organizing-content-23/)
=/=
Finally, it used to be that we enjoyed a monopoly on information. Who else would write about this stuff except us?
Today we have competition, especially in consumer products
Today’s help system is Google; today’s training center is YouTube; today’s support forum is Amazon
Even internally we have competition: everyone posts to the product wiki, so what makes our contributions valuable?
Stop me if you’ve heard this one before: The other day I saw a blog post called “Surviving the Dying Career of Technical Writing”
(http://www.uxmatters.com/mt/archives/2016/03/surviving-the-dying-career-of-technical-writing.php)
Altogether, it’s enough to make you wonder if you should get out of the biz
And after nearly 40 years in the field (over 30 in STC), this is not something I say lightly…
Now, this all sounds depressing, but I promise I won’t leave you that way
In fact, I will address all four of these concerns
So where do we start? How do we tackle these problems in such a dynamic time?
=/=
Mobile is going through a “wild west” phase
=/=
=/=
=/=
One thing hasn’t changed: the needs and problems of users
(We don’t evolve as fast as we invent new technology)
The techniques we learned a generation ago are still valid today, and will be valid in the future
So let’s start there
Do GUIs really need words? Why yes, yes they do, unless they’re trying to be puzzles
How intuitive is this GUI? Can you use it?
(Hat tip Tom Johnson)
Microsoft Developer Library, in fact, acknowledges that “comprehensible text is crucial to effective UI”
They may say “no one reads the doc” or even “no one reads the Help,” but no one says “nobody uses the GUI,” and GUI design is largely text and layout (plus the business logic under the surface)
Let’s run through the types of user assistance, starting with traditional forms
We all know what this is: a help window (this is Eclipse Help)
Still used in all desktop applications
Leads to online version of our books
Monolithic—write once, use once
The Google images I found were all… old looking
Online help is now 25 years old
(A nostalgic gallery of Help windows is available at http://www.guidebookgallery.org/screenshots/help)
Good old tri-pane help is at least 20 years old
Advantages (Matthew Ellison, “New Trends in Online Help,” 2006, http://www.ellisonconsulting.com/downloads/New_Help_Trends.pdf):
Great for reference information
Comfortable and familiar for the author
Enables Help authors to work independently from software developers (we’re not tied to their schedule, and our mistakes don’t break the build—whew!)
Disadvantage:
Forces user to leave application and go elsewhere (“a separate world”)
This is also old, from a 2004 IBM book
Context-sensitive snippets are drawn from a larger help file
(Write once, use in many places)
This example leads me to ask some meta-questions:
What is a maid levy? (what is the user asking for here?)
Stop me if you’ve heard this one before: what did the developer probably say when the writer asked?
(“If they don’t know what it is they won’t be using the program”)
Is it bad that the field label is truncated?
Why is the help not in the same order as the fields? (which one is right?)
Is there help for every field? (Probably—a GUI “travelogue”)
Today we can see traditional information types presented in new forms and places
It’s old wine in new bottles
(When these manuals were photographed they were already 35 years old, and notice that three are still shrink-wrapped, which unfortunately demonstrates Nielsen’s First Law)
My group used to write new-features guides
This serves as, and replaces, a new-features guide
Implemented as an overlay, both the technical term and how it looks
Appears the first time a user launches the application
I like it—it’s visual
We also used to write getting-started guides; this can be a replacement
Implemented as overlays
Appears the first time the user encounters a new feature
Two mobile apps
(left) Windows phone (http://forums.windowscentral.com/developers-corner/326286-how-make-how-use-app-overlay-windows-phone-apps.html)
(right) Android (https://www.nngroup.com/articles/mobile-instructional-overlay/)
Note how little space there is to work with—it’s like writing fortune cookies!
Innovative as they are, these are all examples of information at a remove from the application itself, like a separate application
Still one on top of another
How can we reduce the awkwardness? How can we reduce the distance? How close can we get?
Let’s look at new information in new bottles
(Here’s the technical content for your employer)
When we first talked about “user assistance,” we meant online help
Then “embedded assistance” meant help available from an application (the Help menu)
Then “context-sensitive help” meant linking an application window to a specific help topic
In recent years, “embedded assistance” has crossed the barrier between the program and its user information
Let’s quickly survey embedded assistance, and my approach is … to approach
This definition is from Developing Quality Technical Information, Third Edition by IBM
(other definitions vary)
I will have more to say about this book later
The goal of embedded assistance is to answer questions before the user asks them, by making information available when and where it’s needed
It’s for everyday use (as opposed to the “what’s new” or “getting started” help I showed you earlier, which are first-use)
The book defines eight different levels of embedded assistance for GUIs, which I show here in reverse order zooming in, starting with contemporary context-sensitive help
By the way, the book also gives examples for CLIs: command names, parameters, and defaults
And in addition to software, the book gives hardware examples: physical labels, color coding, as on cables or ports
This is the first level closer
We recognize it as context-sensitive help, but not an overlay, embedded in the window
Also called “help tray” or “help panel” (Oracle)
The next level closer is the wizard
Also known as “assistant”
Popular for installation, configuration, or other multi-step processes
Many examples—here are two, one for software and one for hardware
Here’s an Oracle example of a multi-step wizard with a “train”
The train shows the steps, or stops, and the user’s progress in a multi-step process
The next level closer is hover help
Also called “balloon help” or “popup help”
The user puts the cursor on an object and a snippet of user assistance appears
It answers the question “how do I do this?”
Research has shown that this is our best trick, but…
Problem in mobile: no cursor = no hover = no clue
So our best trick doesn’t work at all on the #1 Web platform
But notice the icon with a question mark in a circle
This finesse works on all platforms including mobile
This is a briefer and more common form of hover help
It can just names the object
It answers the question “what is this?”
There are many examples; three are shown here
(Of course, on mobile platforms it suffers from the same issue as hover help)
Autodesk has taken tooltips to the next level for its Revit building design software
The application is used by users who think visually, it is highly visual itself, and so is the Help
Combines what programming can offer and what writers can say
This is a tooltip that appears if a user lingers over the menu choice
It doesn’t say much, but if you press F1…
=/=
… it expands and gives you more.
But wait, there’s more! If you press F1 again …
… you get a context-sensitive Help topic, part of the full Help
Notice the embedded video available for this topic
(Oracle calls these vidlets)
Autodesk posts these videos to the web, besting the competition
More visually appealing
More reusable content
Meta-questions for writers:
You want me to create a video for each topic?
For which ones, then? Who decides, and on what basis?
The next level closer is messages
Messages are an important opportunity to communicate with the user
Here we cross the line—this is part of the GUI
There are more examples of bad messages than good ones; this is a good one
Let me offer a bad one: What does the HP printer error “PC LOAD LETTER” mean? “Printer cassette load letter”
“Printer cassette” is the HP term, which no customer recognizes
“Letter” is one paper size (8.5x11), common in the US but not elsewhere
Better would have been simply OUT OF PAPER
But that would have been too easy
Nielsen offers a lot of advice on writing error messages
Much of it deals with the psychological state of the user when the message appears
Sometimes we’re asked how to word a message; more commonly we file a bug on a bad one
Support can tell us which messages trigger calls—we could focus on these
It’s an opportunity to bring our skill set to bear on real pain points
When a message appears it disturbs the user’s flow and context. Can we get closer?
Here’s how Oracle cloud applications do it
(you can’t get any closer than this!)
Here’s another error message. What’s the next step? Users contacted support and asked, “how do I manually recover a file?” The task is documented, so Autodesk support would say, “When you see this message, go read this Help topic.”
Here’s an idea: link to the topic in the message
Content is more visible
traffic driven to content
No reason for Support to write their own material
Besting the competition
(Incidentally, “contact Support” is frowned upon at Oracle, which is a cultural change for us, because we used it hundreds of times)
As I said, Autodesk products and their users are highly visual
It would take a lot of words to explain these options
A picture is worth 10,000 words
(I created the “before” image)
This is an Oracle example of how to explain a somewhat complicated process visually, here with animation
If an instruction is crucial, why wait to provide it?
The next level closer is inline text
Also called “static text,” or “supplemental instructions” or “supplemental explanations”
This example is from Autodesk, where a couple of obscure settings are explained by a few lines of static text (I created the “before” image)
Text that explains a page, window, section, or field
Static text is always visible on a page
Doesn’t require user action to display
Works for all platforms
=/=
The more often people need information, the more it belongs as static text
How much to add? Use sparingly; if you have to say too much, that’s a design red flag
Too much text actually discourages reading, so is counterproductive
Here are two examples, a Web application and a mobile app
The static text appears only a few times, not on every field
Why pick those? Experience and common sense
Notice the two links to help, which answer the question “why do you need this?”
The next closest is field input hints
Also called “placeholder text”
(You saw several on the last slide)
Appears in a field and provides:
instructional text
a reminder for occasional users
a hint on how to format data in a field
an input label for a field that is not otherwise labeled
Three examples here
This is not the default, so it must appear typographically distinct from any default value
(you can’t have both a hint and a default)
The closest form of embedded assistance is UI labels
Encompasses labels on pages, windows, sections, fields, menus, controls, and buttons
Four of them here
(Basically, every word in the example is part of a label)
This is clearly what we consider development territory
Better than adding a hint, redesign the label (rewrite)
This Autodesk example shows how a very obscure label was rewritten as something meaningful to the user
Now let’s change gears
This part of my talk was for you to take back to your employer
The next part is for you and your career
Let’s go back to Developing Quality Technical Information
DQTI is a well-known book in documentation quality circles
Third Edition written 30 years after the original version
First Edition: make your books better
Second Edition: addressed “nobody reads the manual” by adding focus on help
I was familiar with the First Edition, but the larger Oracle doc group we now belong to bases their documentation approach on this edition, and they made us all read it
I’m glad I read this edition, because it’s significantly different!
Here’s the book’s statement of intent (emphasis mine)
Third Edition: addresses “nobody uses the help” by adding focus on embedded information
We can recognize and relate to this evolution
I started doing things the first way
When we were bought by Oracle my group was doing things the second way
The Third Edition defines a third way, and advocates adopting it
The book advocates a new role for technical writers today:
in addition to our traditional roles, owning all the words visible in products (emphasis mine)
This includes online help but also the words and graphics in the GUI, and the labels and colors used on hardware
Combines the traditional roles of writing, engineering, and curriculum development
In my opinion, the authors advocate an extremely aggressive—but extremely exciting!—role for us, because it moves us from the creators of stuff “nobody reads” to the forefront of product design
It reverses the playing field. Instead of saying our stuff is part of the product, we’re saying the product is part of our stuff
Nobody says “nobody looks at the GUI,” and we’ve seen that without words, GUIs are meaningless
So owning the words puts us in the front row
So, who buys into this? IBM, for one; Oracle
But how? At the start of this presentation I complained about development environments
In what world do developers pay attention to us? Let me show you
The next part of my talk addresses development methodologies
This is the key to owning the words
Most of us cut our teeth in waterfall methodology
The GUI has always been a difficult space for us to work in because we start with completed code
In my experience, this is an impediment to making meaningful contributions (we have to file “guerilla” bugs, which is labor-intensive and can be resented or ignored)
Can you own the words in waterfall methodology? Yes, but it’s hard, including psychologically
On the other hand, Agile methodology empowers us to fix things, or create them, from the start, when it’s cheap to fix, and when, in my experience, our input is gratefully accepted (this is huge!)
Can you own the words in Agile methodology? Yes, and it’s much easier
I’m currently going through this transition
An Agile project to reimplement the product I’ve been documenting for seven years
I know what you’re saying about now: O noes!
I have to write code? (I can break the build?)
I have to make videos?
This is not a trivial change I’m talking about here
How do we even get to the words? They’re in the source code!
Am I worthy?
User-visible text strings may be distributed throughout the source code, in which case you (and the translator!) have a big problem
Or there may be an interchange file
In the project I’m working on, a JavaScript file contains all the visible GUI strings, including page names, menu names, button names, prompts, and messages
Here is a fragment (it has changed already, and I’ve introduced an error)
You can see how a developer thinks, and why things are labeled as they are
It’s not obvious what we can touch and what we can’t (it’s the stuff in quotation marks)
Existing tools (such as Flare) aren’t meant to create these files, and if you use a text editor like Word, a spellcheck will explode on them
Even changing the straight quotes to smart quotes breaks it
But doesn’t everyone use XML?
This is an Oracle Fusion example, in XML
It isn’t any easier to understand
This looks so hard!
Aren’t usability experts in this space already? Maybe we should leave this to them?
That’s the final part of my talk
The hot field today is indeed Usability Experience (UX) engineering
And for many years, Don’t Make Me Think has been a major, and popular, work in the field
(I learned my lesson this time and went straight for the newest edition)
The more I read of this delightful little book, the happier I got
Quotes Ginny Redish and Tom Johnson
Source of statement that technology changes but user issues don’t
UX was formed from the fields of information architecture and usability
It’s a new field, and its practitioners are searching for guiding principles
Krug offers some
His important principles are entirely familiar (stop me if you’ve heard #3 before: “Omit needless words”)
In fact, Krug validates principles we’ve always thought of as sound in this new domain
Technical communicators and UX experts share overlapping skill sets
Even some of their complaints have a familiar ring (stop me if you heard these before):
“Not starting on the home page” = Every Page is Page 1
“Web designers are web users” = everyone can write
In many areas they are seeking knowledge that we already have
How overlapping?
Here’s another example from another expert (my emphasis)
When I look at this list of the most critical UX principles, I recognize more than half as principles of writing and presentation we’re already familiar with
(Another recent blog post making the same point: http://tubikstudio.com/copywriting-in-ui-words-that-make-design-go-round/)
Are we trying to survive a dying career? Is that what we’re talking about here?
I don’t think so, and let me tell you why
I started this talk by listing four complaints:
People don’t use our work
It’s hard to adapt our work for different platforms, especially mobile
It’s hard (and painful) to get GUI fixes in at the end of development
Users have more attractive alternatives to our work
I’ve addressed those concerns, and laid out the threads of a solution
Do the threads come together?
Here’s the punch line: According to Krug, “the vast majority” of development teams don’t have UX experts
So this is an opportunity for us
This is important, valuable, visible, front-line work
Agile may or may not be more work, but it’s more interesting and rewarding work
And it lets us—even invites us!—to assume the UX role
Iterative, incremental improvement—not all at once, but better and better
My personal bottom line: Owning all the words takes work and learning, but it feels good
I’ve discussed coding
I’ve discussed UX
I’ve discussed video
Have we abandoned the profession, or is this still technical communication in any sense?
I think it is!
For a long time I’ve noticed that technical communication is completely changed since I started, and yet just the same
I recognize this as still technical communication, just evolved
Let’s check…
For example:
We’re familiar with the concept of progressive disclosure, and it can be used to organize specific kinds of embedded assistance (as DQTI has done)
Show a little bit now, and more if the user keeps asking (increasing depth from first seen to last), as Autodesk has done
This puts users in control
This is information architecture
We know how to do that
It still works in this domain
We’ve still got it, baby!
How does it work in the real world? Let me offer a real example
This is a message mockup. The developer asked me how to word this message
It’s one instance of a standard message that will appear in some 40 variants (in legacy product, coded independently by many engineers)
Today, we don’t see messages until the code is in QA; if we don’t like the way they’re written, we file bugs, most of which are deferred and forgotten
Owning all the words? 14 here
Two comma splices (but let’s expand our focus)
Is “Warning” too vehement for a routine operation? Is repeating it necessary?
Does the user care that the object will be deleted from the server? What server?
Saying “object” instead of listing the specific type of item being deleted is vague; but do we want many variants of this to be clear, or only 1 to save source code?
Is the construction “object(s)” confusing? How about saying “object or objects,” coding the message to appear for singular and plural cases, using “object,” or using “objects”?
Oracle guidance on use of the button labels “OK” and “Cancel”: don’t use
For now, we have settled on this wording:
=/=
I’m still learning, and I don’t have all the answers yet
Design considerations and issues:
Level of Effort: Is this work instead of what we do today, or in addition? Locally, the jury’s still out
Process: Embedded assistance lives in source code. Can we store any of it in our CMS? If not, how do we archive and share our work? Is it even ours?
Design: When should we use embedded assistance? Which one should we use? (Decision tables help)
When should we use more than one type for a GUI element?
Style: How should we write each type? (A style guide helps)
Scope: Is this repurposed and sharable work, or new bespoke work?
Information Architecture: Can we map embedded assistance into existing documentation patterns; create a new pattern that includes them; or do we have to throw out what we have and start over?
Priorities: If you’re confused by the GUI, ask
If we do it right, it looks simple, but simple is hard
(yet the work is important—and isn’t that great?)
The career you save may be your own
Here’s an example from Microsoft
The original version has problems:
It’s overlong
The default action is OK, which careless users will click without reading
This is the revision
=/=
Here’s another real-world example
Background: The network topology of sites and clusters needs to be configured; this is a section of the site configuration page
There can be one or two sites
Two sites provides georedundancy—if one site fails the other site takes over
Let’s look at the tooltip (“input range from 0 to 255”) suggested by the developer (who said “please tell me what to say here”)
As defined in the book, this is GUI-level help: it answers the need to know the valid range of input values for this field
The information is useful where and at the moment it appears
What does 0 mean? (it means the site never fails over)
There can be up to 55 servers at a site; what happens if we set the value to 255? (the site never fails over?)
The tooltip is only a suggestion in a mockup. There are multiple layers of embedded assistance; which one should we use here?
How many layers should we apply? To which fields should we apply them?
Issue raised by a developer: How much is too much?
We might need to define the label: what does “Site Failure Threshold” mean? (how many servers have to fail before the site itself is considered to have failed, and the site preference reverses)
Is this standard or proprietary knowledge? In other words, can we expect everyone to know what it means? (proprietary)
The tooltip says what values you can enter for the site failure threshold; what value should you enter?
(When asked, the SME’s long discussion boiled down to “it depends”)
(set high, the site doesn’t fail easily; “If one goes out, the rest stay lit”)
(set low, the site fails over readily; “Divert life support power to shields”)
(Further down in the section, “SIG-A…” and “REP” is proprietary, but I’m told that “VLAN” and “OAM” is standard knowledge that any user will know, which makes me itch)
