Downloaded 63 times
![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](https://image.slidesharecdn.com/embeddeduithirdrailorthirdway-160403210427/85/Embedded-User-Assistance-Third-Rail-or-Third-Way-29-320.jpg)
![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](https://image.slidesharecdn.com/embeddeduithirdrailorthirdway-160403210427/85/Embedded-User-Assistance-Third-Rail-or-Third-Way-30-320.jpg)
Uploaded bySteven Jong
Embedded User Assistance: Third Rail or Third Way?
The document discusses embedded user assistance and whether it represents a "third rail" or "third way" for technical communicators. It presents examples of traditional documentation methods and embedded assistance features like tooltips, messages, and inline help. The author argues that embedded assistance is a viable approach for technical communicators, allowing them to work within agile development processes to directly improve the user experience. Technical communicators can apply established principles to embedded assistance while still performing their core functions of explaining technical information to users.
More Related Content
Similar to Embedded User Assistance: Third Rail or Third Way?
Embedded User Assistance: Third Rail or Third Way?
- 1. Embedded User Assistance: ThirdRail 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 reallyneed 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 2April 2016 Steven Jong, InterChange 2016 5 Eclipse Foundation
- 6. Traditional: Context-sensitive help 2April 2016 Steven Jong, InterChange 2016 6 http://www.ibm.com/developerworks/library/j-javahelp2/
- 7. PRESENTING TRADITIONAL DOCUMENTS INNEW WAYS 2 April 2016 Steven Jong, InterChange 2016 7 From http://www.vintage-computer.com/ibm_pc.shtmls
- 8. New: New-features guide 2April 2016 Steven Jong, InterChange 2016 8 From “Web UI elements,” by Rebecca Reynolds, Pinterest.com
- 9. New: Getting startedguide 2 April 2016 Steven Jong, InterChange 2016 9
- 10. EMBEDDING ASSISTANCE 2 April2016 Steven Jong, InterChange 2016 10
- 11. What is embeddedassistance? 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 2April 2016 Steven Jong, InterChange 2016 12
- 13. Wizards 2 April 2016Steven Jong, InterChange 2016 13
- 14. Multi-step wizard withtrain 2 April 2016 Steven Jong, InterChange 2016 14 Courtesy Oracle
- 15. Hover help 2 April2016 Steven Jong, InterChange 2016 15 Courtesy Oracle
- 16. Tooltips 2 April 2016Steven Jong, InterChange 2016 16 Courtesy Oracle
- 17. Tooltip with progressivedisclosure 2 April 2016 Steven Jong, InterChange 2016 17 Courtesy Autodesk
- 18. Tooltip with progressivedisclosure (continued) 2 April 2016 Steven Jong, InterChange 2016 18 Courtesy Autodesk
- 19. Messages 2 April 2016Steven 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 closerto the source 2 April 2016 Steven Jong, InterChange 2016 20 Courtesy Oracle
- 21. Improving an errormessage 2 April 2016 Steven Jong, InterChange 2016 21 Courtesy Autodesk
- 22. Adding images totext 2 April 2016 Steven Jong, InterChange 2016 22 Courtesy Autodesk
- 23. Animating a hint 2April 2016 Steven Jong, InterChange 2016 23 Courtesy Oracle
- 24. Inline text 2 April2016 Steven Jong, InterChange 2016 24 Courtesy Autodesk
- 25. Inline text—how much? 2April 2016 Steven Jong, InterChange 2016 25
- 26. Field input hints 2April 2016 Steven Jong, InterChange 2016 26
- 27. UI labels 2 April2016 Steven Jong, InterChange 2016 27 From Microsoft Developer Network Library, “User Interface Text”
- 28. Improving a label 2April 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 continuesto 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 techwriter’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? • Thisis 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 MeThink, 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 principlesfor 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? • Allusers 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 stilltechnical 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 appliedto 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: Whatto say? 2 April 2016 Steven Jong, InterChange 2016 41 Courtesy Oracle
- 42. Issues • Doing differentthings, 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 usesthe 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 gratefulto 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 2016Steven Jong, InterChange 2016 46
- 47. Messages and actions 2April 2016 Steven Jong, InterChange 2016 48 From Microsoft Developer Network Library, “User Interface Text”
- 48. Tooltip example: Whatshould 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
- #2 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
- #3 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
- #4 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
- #5 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)
- #6 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”)
- #7 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”)
- #8 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)
- #9 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
- #10 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?
- #11 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
- #12 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
- #13 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)
- #14 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
- #15 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
- #16 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
- #17 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)
- #18 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 …
- #19 … 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?
- #20 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
- #21 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!)
- #22 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)
- #23 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)
- #24 This is an Oracle example of how to explain a somewhat complicated process visually, here with animation
- #25 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
- #26 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?”
- #27 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)
- #28 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
- #29 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
- #30 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
- #31 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
- #32 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
- #33 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
- #34 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?
- #35 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
- #36 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
- #37 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
- #38 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/)
- #39 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
- #40 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…
- #41 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!
- #42 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: =/=
- #43 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?)
- #44 The career you save may be your own
- #49 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 =/=
- #50 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)