Successfully reported this slideshow.
Your SlideShare is downloading. ×

Embedded User Assistance: Third Rail or Third Way?

Loading in …3

Check these out next

1 of 48 Ad

Embedded User Assistance: Third Rail or Third Way?

Download to read offline

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.

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.


More Related Content

Viewers also liked (17)

Similar to Embedded User Assistance: Third Rail or Third Way? (20)


Recently uploaded (20)


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
  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
  7. 7. PRESENTING TRADITIONAL DOCUMENTS IN NEW WAYS 2 April 2016 Steven Jong, InterChange 2016 7 From
  8. 8. New: New-features guide 2 April 2016 Steven Jong, InterChange 2016 8 From “Web UI elements,” by Rebecca Reynolds,
  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,
  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
  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
  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
  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
  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 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
  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), • User interface text guidelines: – Microsoft: us/library/dn742478.aspx – Apple: xperience/Conceptual/OSXHIGuidelines/ 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

Editor's Notes

  • 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 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:
    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.”
    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 (
    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”

    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
    Good old tri-pane help is at least 20 years old

    Advantages (Matthew Ellison, “New Trends in Online Help,” 2006,
    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!)

    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 (
    (right) Android (
    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:
  • 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)