By Julian Cantella | Member
and Michelle Corbin | Fellow
From social media to cloud computing to mobile devices, technology is changing how we live—often so rapidly that it’s hard to keep up with. As technical communicators, we need to convey information in a way that keeps pace with changing technology and meets the ever-evolving needs of our users.
For many of us, the days of producing printed manuals are a distant memory. More recently, we provided information in a linear fashion as PDF files, or in a topic-based fashion as one of many variations of the online help system. Not surprisingly, many of our prospective readers have rebelled—they don’t read the documents, and they avoid the online help like the plague. In response, technical communicators have started to embed information in the user interface (UI), using a set of mechanisms that are collectively known as embedded assistance.
Embedded assistance is an integral part of a product user interface, one that contributes to the ultimate success of a UI. Users of Web and mobile applications in particular demand that user interfaces be sublimely simple and intuitive. Developers of these user interfaces are providing embedded assistance in forms such as labels, controls, tooltip text, hover help text, inline instructional text, or even the text in an embedded help pane. To deliver an effective and usable user interface, developers collaborate with experts in technical communication.
Embedded Assistance Works
The case for embedded assistance is well documented and begins with a simple truth: users often don’t take advantage of traditional documentation. According to a recent internal IBM usability test, most users who need assistance to complete a task prefer to consult only labels, icons, and basic hover help. Users rarely click Help buttons or seek out procedures, whether those procedures are documented online or in hard copy. Trevor Grayling states that when users do consult documentation, they skim the material rather than reading it carefully, and often abandon it if they don’t find what they’re looking for quickly.
Many researchers (Martin et al., DeLoach, Grayling) report that users do use embedded assistance and it actually helps them. Users don’t find embedded assistance to be intrusive; when asked, users who relied on embedded assistance to complete a task often don’t realize that they used a help mechanism at all.
Beyond the usability benefits, quality embedded assistance delivers the benefits of established interaction design principles like progressive disclosure and minimalism. Andrea Ames defines progressive information disclosure as providing only the information that is necessary at any given time and for a specific context. Embedded assistance puts information as close to the user as possible, integrating information into a user’s workflow and reducing the time that it takes for users to find the information that they need. Embedded assistance prevents and helps users recover from errors, which can lower support costs—think inline validation, detection of system settings, and default values.
Finally, when embedded assistance contributes to a professional look and feel, it can even become a selling point. Imagine a demonstration for a complex product. The potential customer, a novice, easily understands the labels, uses the inline text and examples to enter values without triggering errors, and reads embedded help to confirm her understanding of a new concept. As an integral part of the UI design, the embedded assistance contributes to a quality user experience.
Stepping Up to the Screen
Embedded assistance is highly valuable and highly visible, an effort that is clearly worth a significant investment from technical writers. Unfortunately, though, technical editors are often left out of the process.
As with any user-facing documentation, embedded assistance can only benefit from a technical editor’s involvement. Some writers might believe that their input is sufficient and that an editor might muddy the process. Or perhaps writers feel that they are fulfilling the editor role because they are editing prototypes or wireframes that are created by UI designers or developers. But writers, exposed to months or more of design discussions, technology-fueled compromises and workarounds, and other minutiae, might not be able to recognize interaction patterns and other UI elements that are not intuitive. A technical editor brings a fresh perspective, one that can more effectively approximate the experience of a new user.
What’s more, a technical editor is likely to have experience with other products and perhaps know team members on products that faced similar challenges. Technical editors bring knowledge of various style, terminology, messaging, and user interface guidelines. When such guidelines are applied consistently across a company’s products, users recognize common patterns, a common “look and feel,” and can complete tasks more effectively.
Editing Embedded Assistance
To effectively edit embedded assistance, editors must figure out how to adapt traditional editing processes and tools to the requirements of the medium. Because editors are editing more than just the text, additional tasks and tools are needed.
One of the first hurdles to overcome in editing embedded assistance is figuring out how to provide comments and markup to technical writers and UI developers. The UI developers work in code files that list property names and values that display as text in the UI. If technical editors use their standard editing tools to edit those code files, they will be too focused on editing just the text, which is clearly not enough. Although this method might be the most expedient for the UI developer, it does not produce the best end result for the user. Alternatively, the editor can take a hands-on approach and use a current build of the UI as part of the editing process. This method allows the editor to test interaction patterns as well as content; however, the time commitment and resources that the option requires might make it impractical.
An effective way to edit embedded assistance is to work with a set of slides that include screen shots of the user interfaces. The technical writer annotates the screen shots, showing any layer of embedded assistance that requires user interaction (tooltips, hover helps, or help panes, for example). If a message is not shown in the screen shot, the technical writer can include the message in the annotations.
Figure 1 shows an annotated screen shot that a writer might submit to an editor.
When an editor receives material in this format, the technical editor can review and insert comments directly on or next to the UI elements and embedded assistance.
In our example, the editor might use the same tool that produced the slides to provide comments and edits. Figure 2 shows some of the comments that an editor might provide.
As with any edit, the writer interprets and implements the comments. However, embedded assistance requires an extra step: the implementation in the UI itself. Again, the writer can use screen shots and slides to help UI developers understand the required changes. For Figure 3 the implemented edits result in the following screen.
Depending on team processes and preferences, these slides can also include links to the user interface guidelines being followed, key design documents that the UI developer wrote, or other resources about the UI context. Editors can work with writers and the product team to ensure that the slides include all of the information that is required to effectively edit and implement the embedded assistance.
Embedded Assistance Challenges and How to Address Them
Although the case for editing embedded assistance is substantial, collaborating on embedded assistance poses a unique set of challenges for technical writers and technical editors alike. This section lists some of the challenges that editors might face and provides tips for addressing those challenges:
Style guides. Technical editors and UI developers might have their own distinct sets of guidelines. Although technical editors bring knowledge-style guidelines to the table, these guidelines must now be considered in the context of UI design.
Tips:
- Resolve differences among style guides and, where necessary, be willing to compromise or recognize the need for evolution.
- Early in the process, work with the writer to provide the team with an “embedded assistance specification” that lists the types of embedded assistance that will be used in the product and that refers to specific embedded assistance guidelines.
Screen real estate. A technical editor should always encourage minimalism, but user interfaces often require trade- offs between concision and clarity. The challenge only increases with complex user interfaces and mobile applications.
Tips:
- Determine what text goes in which type of embedded assistance and do not duplicate content between layers.
- Use words that are standard, immediately apparent, and consistent across the product.
- Draw from guidelines to set standards for how much text can be provided in each type of embedded assistance. Remember that translation can double the amount of space that a given text string consumes. For example, you might set a standard that limits tooltips to 100 characters in English to allow for 200 characters in German.
Familiarity. The same lack of immersion in the product that gives technical editors a fresh perspective might also limit their understanding of context. Editing user interfaces requires a broader focus, one that encompasses much more than the knowledge that was required for old-school information delivery mechanisms.
Tips:
- Before even taking pen in hand, read some of the design documents or schedule a UI walkthrough with the technical writer (and UI developers, if need be) to understand the context for the embedded assistance.
- Learn which platforms the user interface will run on and which user interface standards or patterns they are adhering to.
- Attend product meetings where user interface design is planned, discussed, or reviewed. The need and ability for an editor’s involvement in lower-level discussions and decisions depends on factors such as the writer’s experience and time.
Visibility. Embedded assistance is seen by everyone on the product team, from developers to quality assurance to product management. Stakeholders who might take little interest in more isolated documentation are likely to have stronger opinions about embedded assistance because they see it as part of their own day-to-day work with the product.
Tip:
- Take all of these views into account when making editing comments, and understand that the comments must now speak to multiple audiences. For example, you might need to provide more detailed rationale for a particular comment, such as listing the guideline that supports your suggestion.
Iterative interfaces. Every user interface evolves, and technical editors won’t have the exposure, or ultimately the time, to provide input for every iteration.
Tips:
- Work with writers to determine the best time (or times) in a project schedule to provide input.
- Provide input that enables technical writers and UI developers to craft consistent quality embedded assistance on their own and apply the editing comments to other user interfaces.
Implementation. Technical writers and editors don’t always have direct control over the files that contain user interface text.
Tips:
- Ensure that UI designers and developers implement the changes to the embedded assistance. Be vigilant and collaborate with the entire development team.
- Request access to product builds so that you can help the writer verify implementation.
- Consider attending meetings in which the UI is reviewed by the product team. Provide a supporting voice for the writer.
Collaboration Is the Key to Success
Creating usable embedded assistance requires the skills and abilities of everyone on a development team: product managers, UI developers, QA engineers, technical writers, and, yes, technical editors. To meaningfully contribute, editors must integrate into the team dynamic.
Just as users expect something beyond isolated print manuals or PDFs, editors can expect to leave behind the days of editing in isolation. A completely nonverbal exchange—receive the writer’s material, write comments, return the marked-up information, move on—won’t cut it for embedded assistance. Editors can attend team meetings, consult regularly with the writer or other team members, and generally become a recognizable face. As an advocate for the writer, for simplicity, for quality design, editors can help provide the intuitive user interfaces that today’s users demand.
Julian Cantella is an information developer for data quality products at IBM. He also works as a technical editor for research articles about privacy and security. He holds an MA in professional writing from Carnegie Mellon University.
Michelle Corbin is an STC Fellow who works as a senior technical editor, terminologist, and information architect for data quality and big data products at IBM. She has over 20 years’ experience in technical communication. She has won the Frank R. Smith Distinguished Journal Article Award twice. She wrote the chapter, “The Editor in the Modern Organization,” in New Perspectives on Technical Editing, edited by Avon Murphy. She is currently teaching an online certificate course for STC called Technical Editing Fundamentals.
References
Ames, Andrea. L. Enabling Progressive Information Disclosure with the “Stages of Use” Model. Paper presented at the Technical Communication Summit, Rosemont, IL (May 2012).
Chong, Lorna, and Rita Claar. IBM internal usability study, 2012.
Grayling, Trevor. If We Build It, Will They Come? A Usability Test of Two Brower-based Embedded Help Systems. Technical Communication 49 (2002): 193–209.
Martin, A. P., M. Y. Ivory, R. Megraw, and B. Slabosky. Exploring the Persistent Problem of User Assistance. Technical Report IS-TR-2005-08-01. University of Washington Information School, 25 August 2005.
Robertson, Jenny. Developing onscreen user assistance. Paper presented at the WinWriters Online Help Conference, Seattle, WA (February 1999).
