By Ronnie Seagren
and Laura Gardash
As editors and writers become more involved in developing mobile and desktop interfaces, our role continues to evolve. Rather than contributing documentation that clarifies how to do a task after the user has tried and possibly failed, we determine how to disclose helpful information progressively right in the interface, helping the user make good decisions and preventing errors that lead to expensive support calls.
It’s not just the programs that keep changing in the software industry. As those who create the supporting information for those programs, we are evolving too, as we must. Rather than 1,000-page manuals, people want their help in easy-to-digest portions.
Although manuals moved online, and then help topics replaced manuals, technical editors and writers often remained on the development sidelines. Our work provided information for users of the products and helped with problems in products; our participation was often seen from the development point of view as supplemental or peripheral.
The information evolution has been coming for a while, moving ever so gradually but necessarily from paper to PDFs to online help, from next to the product, deskside, to directly in the product interface. And our roles have been slowly shifting from translating developer-speak into being user assistance engineers, especially now that we are knee-deep in the mobile evolution.
As IBM information architects Andrea Ames, Alyson Riley, and Deirdre Longo remind us in The Strategic IA column in the April 2012 issue of Intercom, each of us might be thinking we are not a user experience designer. They argue that we are, and always were, designing the information experience. We just have to be more upfront about it now.
Apps as a catalyst for change
Why do people love mobile apps so much? Because they are intuitive. They build on what we already know, so the learning curve doesn’t feel like much of a curve at all. If we don’t already know how to do something, the labels clearly communicate what to do where and when. A complicated app quickly becomes a relic: we uninstall it because, hey, it cost us only a few dollars anyway. We never open a manual for an app. We never have to.
Users of enterprise-wide programs are willing to stick it out a bit longer because they rely on the programs to complete their work. They use them, although begrudgingly, if the programs do not work as intuitively as their personal apps. But how much longer will users put up with programs that are so challenging to understand that they have to turn to the documentation to use them and get on with their day? The answer from users is “not much longer at all,” because these same users turn on their iPhones after work and sigh with relief as they use their apps with ease.
We can learn from apps. Providing assistance right in the interface makes more complicated products easier to use, improving satisfaction and moving users closer to possibly forgetting that they’re using assistance at all as they just focus on getting their work done.
As Julian Cantella and Michelle Corbin state elsewhere in this issue, “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.” The medium influences the message and then—poof—disappears.
Incrementally becoming essential
So where do the technical editor and writer fit into this approach? Instead of explaining what’s in the user interface in the documentation or help topics, we now work with development to embed all the information about the interface right in the interface.
Embedded assistance provides a structured way to give users only what they need to help them make the decisions at hand, right where they’re working, with easy access to more information if needed. They can make informed decisions and avoid wrong choices that often lead to expensive support calls.
With embedded assistance, our work no longer ramps up when development stops. As we become involved in interface development, we help create or review the interface during the development process.
Although the specifics might differ depending on how your team is organized, by providing embedded assistance or editing the interface as a whole, your role moves from supplemental to essential.
Getting ready to make a difference
This all sounds very interesting, you think, but how do I get started? How do I reinvent the wheel that is the development process? Here are some ways we have found useful in shifting our roles with the teams we work with.
1. Establish the roles
In the transition to embedded assistance, everyone’s role changes. It’s important to determine who owns the text and who has a say in it. In small teams, the editor and writer might be the same person and might also create training materials. In large teams, difficult design decisions to refine the scenario might involve user experience people, designers, architects, and people who work directly with customers. In some products, writers actually own the text on the interface. If there is a design document or an explicit process, we find it helpful to note that input from editors and writers is mandatory. In a very agile environment, scheduled review times before the end of each iteration or translation drop can ensure that everything is edited.
Because most of the assistance can move to the interface, developers and writers must work with each other, open to and responding to input on everything from programming limitations to the placement of objects on a screen for a common task flow, from the wording of field names and check box labels to what elements are considered advanced.
The development culture begins to change. Eventually, developers come to see input from editors and writers as standard. With each release, editors and writers get more comfortable with gradually working through the software, improving the embedded assistance for common task flows. And the more agile your project is, the more iterative and collaborative this process becomes. Remember that you have to lead the way or, as Ames, Riley, and Longo warn, “information might continue to be a secondary consideration in the discussion.”
2. Determine timing for edits
Writers work side by side, often incrementally, with developers, so you might wonder why we keep talking about the editor. Technical editors can provide training and serve as a style resource to enforce or even create guidelines and standards. Editors can recognize potential legal issues. For a larger product, where everyone works on smaller parts or components, the editor might be the only one to systematically review the product interface or cross-product interaction from a user’s perspective.
Editors can set a time to do a systematic review. A new product might require two reviews: the first at an early milestone in the development process or before a beta release, and another before the interface freezes. For a product update, a later review might be all that’s needed, or you might want to focus on new function.
3. Keep deepening your understanding of your users
As always, your users should be front and center in determining the design. The more you understand the scenarios, use cases, and tasks they will want to do with your product or component, the easier it is to raise useful questions when a proposed interface is difficult to explain or requires extensive text to describe. The most important thing is to recognize when a task works from the development point of view but does not fit into the domain model of your users.
4. Look at the interface systematically
Determine how you will do the edit. Again, writers will probably work incrementally with developers. However, for a systematic edit we find it helpful to take screen captures of the screens and paste them into a document or presentation in the order of accomplishing common scenarios or task flows.
In the document you can use callouts for annotations, add questions, or even add suggested mockups. You can also suggest moving information to another form, such as using a text box for hover help or tooltips. You can track review comments as needed.
5. Find documentation that can move to the interface
We spend more of our time working with subsequent releases than with new products. If you already have documentation, scan it for topics that document the interface. Start with topics about wizards, which by nature should be self-contained. If you have topics that explain what’s on the user interface, move that information right into the interface where the user can find it quickly.
Search for words about using controls, such as click, select, next, browse, and OK. The tasks that contain these terms reveal places where your documentation might be trying to explain interfaces that could become more intuitive. Search for words like tip, hint, important, and note, which often suggest information that users would prefer to know while they’re using the interface. If you can’t move the information to the interface, at least you might be able to provide a direct link.
You can also find content that can move from the documentation to the interface by looking at decision points in the user’s task flow. Sometimes the interface links directly to the topics that help users complete or make decisions in that part of the interface.
Ultimately, anything that is traditional help, especially if it explains how to use the interface to accomplish a task, can be eliminated as the interface becomes more intuitive or moved to embedded assistance.
Not only does it help users to have the help right where they need it when they need it, but moving content right into the interface reduces documentation maintenance and content management problems. No longer do you have to make minute changes in the documentation to keep up with changes in the interface every release. You also reduce the amount of documentation that needs to be translated. And for important supplemental information, smaller but targeted information sets are far easier to use.
Editing the interface
What do we do when we edit the interface? Is our role to choose headline- or sentence-style capitalization for labels and other interface elements? Is it to ensure that the strings are grammatically correct and easy to translate? Is it to ensure that the terminology is consistent and understandable to our target audience? Is it to figure out what’s missing? Yes—and so much more.
1. Clarify where users start
When you open a GPS or restaurant application or even a wizard, you usually don’t have to figure out where to start. Some of the programs we work on are much more complicated. If it’s not clear how to get started, add a prompt or a line of text to suggest where to begin. For example, in more complex applications there are many places to start: you could select New project from a main menu or you could import a project and implement it as-is or modify it.
Similarly, if most users might follow one task with another, try to provide a direct programmatic link that opens that part of the program.
2. Anticipate what can go wrong
Examine the interface so far in the design or in the product, looking at how users complete common scenarios or task flows, across components or even products. What choices do they have to make? What observable behavior or outcome will result from each screen? Is it clear where to go next? How does this functionality tie into the task flow as a whole? Are the terms familiar to your users? Can you use more terms that are more intuitive for your users?
Your goal is to provide the appropriate user assistance at the right point to help the user avoid errors. See where you can increase consistency, not only of style, but also task flow (how you do something across parts of the product). Sometimes you will find unspoken assumptions or missing connections between tasks.
If you have information from support calls or customer feedback, look specifically at areas that prompted complaints. Identify where people reported problems or might make errors. Where could they go wrong? What are the implications of each mistake?
3. Make the fields and controls foolproof
Review the interface, recording your edits and feedback. At each point, imagine what you would say to your users to help them use the software to complete their task efficiently. How much do you understand about the users’ conceptual models of their work and work flow? What do they know? What do they call things? Where are required elements set? Are required fields marked? Test alternative flows and terms.
Whenever possible, the program should detect the user’s settings from the system environment or information that the user has already entered into the system and prefill fields with them. To minimize the need for input, suggest autocomplete and type-ahead if the system can finish what the user starts, such as code assistance, past searches, user-defined functions, common operators, server settings, and possible values. Ask the developer if entries can be autocorrected while being typed.
Write clear labels, in-field help, and onscreen help right where the user needs it. Suggest setting defaults and providing constraints in fields to guide users down the preferred or more common task path. Make sure that anything the user types is validated for length, characters, and content. Examine limitations: if a field asks for a server, can you show a pick list of the existing servers? If you can attach only JPG files, add that extension as the default. Sometimes it is useful to add an example directly into the field or in onscreen text instead of providing a default.
You might think that the next option is to provide more help in context by using a control such as F1 or a question mark, but you can usually avoid that by clarifying fields and controls such as radio buttons and check box labels. For novice users, add more information with hover help without cluttering the interface for more-experienced users. Consider adding links, directly from the hover help if you can, to topics that provide supportive information for the task that the interface is helping them with. Review the tooltips for icons to make sure they indicate actions to take. If information is still missing, consider adding text on the interface to explain a step or provide a brief example, as explained below.
4. Write onscreen text and hover help
In each screen, what do users need to know to complete their work? What might they need to know about the consequences of what they’re doing—especially something hazardous or permanent? Are they deciding something now that they can’t ever change? Will choosing something here limit or determine choices later on? If you’re lucky enough to meet with your customers or do formal or informal usability tests, where do users stumble, have issues, or request more information that can’t be resolved with interface redesign?
Keep embedded assistance short, especially when your product is translated. Because users want to flow quickly through the interface to accomplish their tasks, they don’t want text-heavy interfaces to slow them down. In general, aim to keep introductory information, hints and tips, consequences, and validation messages to no more than two sentences or phrases of 50-75 words. There are cases where a bit more text helps introduce a task, but apply all your minimalism skills.
You can write inline text for a page, field, or control. If you find your text repeating the name of a label already on the screen, or if a field has default or sample values, inline text might be redundant. Sometimes users need a judicious example of what to enter in a field. If required fields aren’t marked, add an asterisk to the label (*).
For icons, check whether there are tooltips. Sometimes you can add a word or two that indicates how to use something, or change the name to a more task-oriented phrase. You might find that a tooltip is inherited from a component building block and doesn’t make sense in the new context. Sometimes icons are cumulative, with “decorators” added for functions that become available after certain actions, such as the familiar yellow star for a favorite or arrows to show the direction of import and export actions. If you can’t change the hover text when the icon changes, ensure that the user task flow is clear in the interface.
Remember that every time people open a screen, they see the onscreen text. To reduce onscreen text, which experienced users might consider clutter, move information aimed at novice users into hover help or make it accessible with the click of a help button or question mark control, depending on the capabilities of your software. For example, in a complex application, you might want to include examples for more novice users. You can create a convention such as “Example:” to save words or use a collapsing section if your software permits. Or you might find hover help works to provide a bit more for novice users or to explain less common functions (adding more information without cluttering the interface for more-experienced users). You might use question mark links or another mechanism to lead users to useful topics. A “Learn more” link can point to explanations of key concepts that they need to make decisions yet not distract the experienced user.
Whatever approaches you choose, use them consistently so people know what to expect. For more information on designing embedded assistance for multiple and evolving audiences, see Andrea Ames’s article, “Enabling Progressive Information Disclosure with the ‘Stages of Use’ Model.”
Do not rely too much on hover help. It might just be on its way out, considering that this functionality does not exist in the mobile environment. Developers of mobile apps, according to Ames, Riley, and Longo in “Mobile: The Crucible of the Information Strategy,” must “have a model that uses every bit of available text [labels, input hints, and other static text] in the most effective way.” And so should we, wherever our users access our software.
5. Improve the messages
When users make an error, they should get a screen message. Sometimes they have to check log files. Use your edit of these messages to prevent user errors in the first place. Writers often review messages when they are written, but many get missed. Before key releases, schedule an edit of new or changed messages. Before a new product is released, try to edit all screen and error messages.
Make sure messages include enough information to be useful. Input validation pop-up text should help prevent errors. These are easy to edit because they relate directly to the user’s situation. You can often suggest adding a variable to help the user understand what happened. Sometimes you can point to the next task in a confirmation message or provide a link to open another part of the program.
If the users need to look at a log, make sure they can find the right one. Sometimes users have to contend with more than one log even to find the relevant messages about an event. Make sure that log messages explain what happened and suggest possible ways to recover from the error.
Technical editors and writers are oriented to both users and standards, which makes us ideal to edit messages. We are often asked to review a file of message strings, which can be little more than a copyediting exercise. To make sure that each message is useful and none is a dead end, we have found it useful to work with developers and search the code to understand the situations that can generate the message. Sometimes several situations result in the same message, which can be untangled by creating distinct messages for each cause. Although some development-time messages should never appear to users, we’ve all seen that happen. There is nothing more frustrating than getting a catastrophic exception.
Users often use Google to search for messages when they are confounded. By ensuring that each message explains what happens and includes actions that help the user recover or at least know what to do next, editing contributes substantially to users’ success using complex programs.
Where does that leave the documentation?
So then what ends up going into the documentation with this approach? If we hit the mark, not so much. Complex apps cannot be simplified as much as mobile apps, but it’s good to try. If we build our task flow and interfaces on concepts that our users already know, there will be less to clarify or define. Scenarios will become clearer because even complex tasks will flow smoothly from subtask to subtask.
However, this is easier said than done, especially with complex products. Until we get there, supportive information about the product, such as planning, overviews about how your product works with others, concepts that users need to understand to work through scenarios, and tutorials based on those scenarios all go into the documentation or in help topics linked to from the interface. But lower-level information, such as detailed tasks and some reference information, can go directly into the interface.
Conclusion
Technical editors have always been user advocates. There is so much potential for improving our products by broadening the traditional editing and writing roles. By getting involved from the early stages of design, editors can help writers think more but write less. We can all clarify task flows right in the product instead of explaining them in documentation that requires the user to leave the task flow to understand it. By further understanding the goals of both novice and experienced users, we can lead development in building quality user assistance into our products. We can hone embedded assistance as an integral dimension of great software design.
Most importantly, we can improve the user experience so that we achieve the “blurring of information and interface” described in “Mobile: the Crucible for Information Strategy.” Our users won’t even notice that we were there.
Ronnie Seagren (seagren@ca.ibm.com) is an advisory technical editor for Rational products at IBM. She has worked for over 20 years with product information as a user advocate and information architect, with a focus on quality and findability. Her recent presentations include the 2012 American Society of Indexers conference in San Diego, the 2011 STC Indexing Day in Toronto, and the 2011 Indexing Society of Canada’s conference in Vancouver.
Laura Gardash (lgardash@ca.ibm.com) is an advisory technical editor for Business Process Manager (formerly WebSphere) products at IBM. For over 10 years, she has focused on the users’ goals and challenges, striving to bring usability across the interface in every aspect of user-product interaction. Before IBM, Laura was a technical editor and writer in the software and trade magazine industries.
References
Ames, Andrea L., Alyson Riley, and Deirdre Longo. Mobile: The Crucible for Information Strategy. Intercom (April 2012): 29–31.
Ames, Andrea L. Enabling Progressive Information Disclosure with the “Stages of Use” Model. Preceedings of the Technical Communication Summit, Society for Technical Communication (May 2012), available at www.stc.org/images/proceedings/Documents/enablingprogressivei1.htm.
Cantella, Julian, and Michelle Corbin. Embedding the Editor: Tips and Techniques for Editing Embedded Assistance. Intercom (September 2012): 11–14.
Nielsen, Jakob. “Jakob Nielsen Answers Usability Questions,” (March 2000), http://slashdot.org/story/00/03/03/096223/jakob-nielsen-answers-usability-questions.
