When creating online help or user assistance, a common practice is to include a related topics link at the end of a given topic. The link usually appears as a clickable button labeled Related Topics or See Also. When a user clicks the button, a pop-up list of related topics appears, as shown below. Each topic is a clickable link.

In MadCap Flare, you can create this type of link using help controls. Flare offers three types of help control, and my favorite is the Concept Link. This control builds a dynamic list of topics that are associated by a concept. You first have to insert concept markers into the topics to create a concept association among them. This type of linking relationship is similar to A-links in other help tools.

Inserting a concept marker

Before you insert a Concept Link help control into a topic, you need to add a concept marker. To insert a concept marker, follow these steps:

1. Open the topic.
2. Open the Concept Window: View > Concept Window.
3. Do either of the following:
   • Add a new concept term by typing it in the entry field at the top; or
   • Select a previously added concept term from the list in the lower half of the window. For each existing term, you can click the plus sign (+) to the left and view a list of topics that are associated with that term. You can also drag terms into the open topic to create new markers.

I usually place both concept and index markers at the very beginning of a topic, before the topic title.

Creating a pop-up concept link

Now that you have created concept associations among topics by adding markers, add a concept link to the end of each of those topics. This procedure creates the pop-up link that users see in your help output.

To create the pop-up concept link at the end of a topic, follow these steps:

1. Open a topic that contains a concept marker.
2. Select the following menu command:
   Insert > Help Control > Concept Link (A-link).
3. Select a term on the right.
4. Click the directional button in the middle of the window to copy the term to the left side of the window.
5. Click OK.

Other types of help control

Flare offers two other types of help control. You’ll find both of them using this menu command: Insert > Help Control > [Type of Control].

Related Topics control

This control enables you to manually build a list of related topics by selecting files. The control appears as a button with the label Related Topics.

For more information, see these help topics:

• Inserting Related Topics Links into Topics
• Editing Related Topics Links

Keyword Link control

This control builds a dynamic list of topics that are associated by an index keyword. You first have to insert index markers into the topics to create a keyword association among them. The default label for the control is Search Index.

For more information, see these help topics:

• Inserting Keyword Links into Topics
• Editing Keyword Links

Another Option: Relationship Tables

When MadCap introduced DITA publishing capability in Flare 5, they cleverly integrated DITA relationship tables as yet another way to introduce related topic links. You can use this powerful feature in non-DITA projects. For more information, see About Relationship Tables.

Questions?

Help controls and relationship tables enable you to give users a simple way to find related information. They also enable users to learn by association. I encourage you to use these features when using MadCap flare to develop user assistance.

If you have questions or comments about these techniques, please add a comment or contact me.

Back to top

My life as a new condo owner is currently filled with moving details and arrangements: cable installation, lock replacement, and minor upgrades and fixes resulting from our home inspection. One detail that caught me off guard and required some research was the selection, purchase, and installation of a new garbage disposal.

Let’s face it: garbage disposals are not one of those things that an average person thinks about. Unless your unit is on the wane—or as in our case, dead—you’re unlikely to wake up one morning and say “I think I’ll shop for a new garbage disposal today.” You probably won’t find yourself habitually gravitating toward the disposal display in Sears, either.

But for the past few days, I have been preoccupied with garbage disposals. My browser has been choked with an array of tabs, each displaying search results and home improvement sites. I have been reading specs, making comparisons, and learning the jargon. I learned to pay attention to specific attributes: continuous feed, sound insulation, grind chamber capacity… induction motor vs. permanent magnet motor…

One model even comes with a “self-service wrenchette … for easy clearing of jams.” My word processor doesn’t recognize wrenchette. I suppose that’s a sort of faux French word for “little wrench.”

Another model makes your life easier because

two grind stages let you quickly grind difficult food waste you wouldn’t put in a standard disposer, like celery and potato peels.

I hate when food waste is “difficult.”

Learning through research

Like most people, I start with the Web when I’m trying to tackle a new knowledge domain. Through research, I was able to narrow down my choice of product and find out where I could purchase it.

Conducting Web research reminded me that I cannot search the Web without informally evaluating the usability of sites. None of the sites that I found explained the meaning of the disposal product specs. The meaning of some terms was obvious, and I could infer the meaning of other terms such as grind capacity. But terms such as sink baffle kind of… well… baffled me. I went on a wild word chase: baffle as noun = “something that balks, checks, or deflects.”

OK, I realize that these sites simply want to sell products, but a good customer is an educated customer, right? A little embedded help can’t hurt.

Learning from experts

My research also reminded me of the discovery process that we technical communicators constantly employ whenever we start a new project. I thought of all the domain knowledge that I have acquired over the years.

At one point I oversaw a large-scale training project at the World Bank. The Bank was rolling out an ERP system, and I was responsible for developing training for the procurement module. I had never worked in procurement, and I spent many hours attending meetings—even on Saturday mornings—with procurement experts.

At the National Cancer Institute, I took on medical terminology thesaurus management. I dove deeply into papers and books on Description Logics and Knowledge Representation. I worked closely with information scientists. I developed a fascination with Tim Berners-Lee’s idea of a truly semantic Web.

Over the years, I have become immersed in many other domains, including telecom engineering, clinical care, accounting, mortgage products, law office management, and manufacturing plant flow simulation. The key to acquiring domain knowledge is to work closely with subject matter experts, or SMEs (pronounced “smeez”).

In one of my most successful projects at the United States Mint, my SME was a seasoned accounting professional. Our task was to produce a training course for the customized accounting module of another ERP system. We worked under a seemingly impossible deadline, using a collaborative strategy where my SME developed raw content for conceptual detail and exercises, and I provided additional writing, editing, organization, and overall design. We met the deadline, and our course was well received.

Projects where software developers were the appointed SMEs did not always proceed as smoothly. In most cases, software developers are in the same position as information developers. Like us, they have to acquire the domain knowledge and expertise to truly understand the needs of the users.

Users are the real SMEs. They use the products and follow the processes every day. Spend time with them. Observe them. Listen to them. Learn from them.

What’s your story?

What on-the-job knowledge have you acquired over the years? Which domains were especially challenging? I hope that you will share your stories.

Back to top

As writers of technical content, we strive to help reduce the number of technical support calls. Yet, a recent post on the blog of LugIron Software refers to a quote stating that documentation can also increase the number of service requests.

Why?

Users feel overwhelmed

The first point in the quote states that overly comprehensive documentation scares users away. That may be true, but comprehensive simply means “of large scope” (Dictionary.com) and says nothing about the quality of the documentation, how it is organized, or how it is tuned for search.

If you deliver a voluminous, printed tome, users will most likely avoid it. If you deliver a help site without clear points of entry and orientation, users will probably look elsewhere. If your information is difficult to browse and search results are low to non-existent, users will give up.

You can improve the likelihood of user satisfaction by

• Performing a careful user and task analysis
• Single sourcing your content for modularity, reuse, and consistency
• Ensuring that your information provides maximum search returns
• Tailoring your information products to support roles and tasks.

For example, nearly all users can benefit from a simple Getting Started guide or tutorial. The guide can cover installation and configuration and then provide a basic orientation to your software. Emphasize what they can do with the software—not how cool the UI is. From there, give them branching options tailored to their roles and desired outcomes.

Users feel stimulated, but…

The second point in the quote bears repeating:

Documentation has so much cool stuff described, that it makes people’s imagination stimulated and they start thinking of other, even more exotic stuff they want to do but can not figure out and start a service request for it.

This statement is indicative of a damned-if-you-do, damned-if-you-don’t problem. I have to wonder how user assistance information has been presented and organized if it is perceived mainly as describing “cool stuff.” I also wonder how it’s structured. My earlier comments about organization, orientation, and findability apply in this case, too.

Regardless, the “cool stuff” aspect of software is a two-way street. If users want to improve the product or take it to another level, they need to provide feedback in the form of feature suggestions and enhancement requests. Product development teams cannot read their minds or restrain their imaginations.

Users feel enabled

Documentation that’s engaging should also make users feel that they have control. So how do you enable users without giving them too much?

You have created user profiles for your product, right? So why not ask “what type of user are you?” and give examples of typical users and associated tasks? Or ask “what would you like to do with Product X?” Then give readers some suggested branching points based on their roles and relevant tasks. Software and documentation need to be integrated in a way that provides a solution for getting things done.

Too often we waste a lot of words that over-emphasize the UI instead of including a separate UI reference section. If you find that you are constantly referring to the UI in ways that are not essential to performing tasks, then ask yourself whether the product design is truly effective or overly cumbersome. That may lead to a separate, challenging but necessary discussion for your product team.

Users feel involved

Our industry is buzzing about ways to get users more involved in contributing to product documentation by applying their product experience. Give them a voice and a stake in the process.

I completely support this approach. As a user, I rely heavily on active, peer-to-peer forums that not only share troubleshooting information but also “cool” tips. I understand how such forums can lessen user frustration and generate user excitement.

If you implement a process to enhance your documentation with user-generated content, don’t be surprised if the regular contributors comprise a small subset. Many users just want to use the product to get their tasks done. They don’t want to write the documentation. So even your participating users need to understand that the documentation must motivate, engage, and most importantly, provide answers for all users.

Even when user-generated content becomes part of your process, someone must manage it and ensure that it is accessible and usable. The most effective forums in which I participate have strong leadership.

Users feel bored

Regardless of what motivates or scares users away, I believe that our industry overlooks some of the obvious reasons why documentation often sucks. One factor that we ignore is the pervasive, stodgy writing style.

Companies should take a long, hard look at their style standards, or lack thereof. In this day and age of more casual conversation, why not integrate a more conversational tone into your documentation? As a long-time editor of tech docs, I have lobbied for a less formal tone for years, and I’m a lot older than many of my vibrant young peers.

Examples:

• We continue to write about how software “allows” or “lets” users accomplish a task instead of how it enables them. The only contexts for the word allows are access and security. And in a software context, I think that “lets” sounds ridiculous.
• We write “If you wish to…” before notes and tasks. We’re afraid to use the stronger and less formal want, or simply the infinitive form: To do x, click y. Wish connotes longing.

  Read: “When you wish upon a star…”

  I’d wager that while using our software, users are longing to finish work and go home. Do you ask friends or colleagues if they wish to go to lunch?

• We use may instead of the stronger, more enabling can. This usage sometimes creates confusion about whether we are giving permission or expressing that something might happen (as in maybe).

These examples are often defended as “polite” usage. I simply believe that they make our words far less engaging and even a bit dull. They create the impression that software is controlling users instead of putting them in the driver’s seat.

Of course, software documentation isn’t the only kind of technical writing. Making policies and procedures sound more informal isn’t easy. Writing about the installation and operation of heavily regulated equipment is a serious business where inaccuracies and mistakes can have serious consequences. But I still believe that even those types of writing can benefit from clear, plain language that sounds more natural.

I’m not advocating a departure from formal writing, but I believe that we are redefining our definition of what’s formal. I have often wished—that is, longed for—a change, and I welcome it.

But I digress. Plain language is a subject for another post.

Users feel content

The rise of social media brings new possibilities and new challenges that are making us rethink how we provide user assistance. Regardless of what we try and what we find effective, we need to remember that what we are delivering is user assistance. The bottom line is, users use our products, read our policies, install, configure, and operate our equipment for one purpose: to get things done.

So when you develop information for users, keep these things in mind:

• Give them a clear orientation so that they can decide where they want to go.
• Stop focusing on the “cool” factor of your product.
• Strive to increase the likelihood that they will find what they’re looking for.
• Consider their roles and provide tailored information.

I welcome your comments and hope that you will share your own solutions for creating a better user experience.

Back to top

Days have whirled by since I returned from the west coast on April 5th. I had planned to write posts about both of the conferences that I attended while I was away, but I have been consumed with a new project, a condo purchase, and moving logistics.

For information about DocTrain West 2009, see these posts:

• Read about the Firefox book sprint
• Read about DocTrain West 2009 sessions that I attended

This post focuses on the WritersUA 2009 Conference for Software User Assistance, held this year in Seattle. In case you are unfamiliar with WritersUA (formerly WinWriters) or have never attended a WritersUA conference, I encourage you to do all of these things:

• Visit the WritersUA site
• Join the WritersUA email list
• Learn more about WritersUA conferences and plan to attend next year’s conference

The 2009 conference setting

The WritersUA organization is based in the Pacific Northwest (my favorite part of the US), so their annual US conference is usually held on the west coast. Last year’s conference was in Portland (Oregon), and this year’s was in Seattle.

When I attend conferences, I like to arrive at least a day early for pre-conference sessions. I also like to get out and explore the city where the conference is being held. I had previously been to Seattle during summer, so I hadn’t experienced its characteristically chilly, rainy weather. But I have explored Portland, Paris, and London in rainy weather, so I made the best of it.

Since this was my second visit to Seattle, I didn’t visit any tourist attractions. I had seen most of the major sites on a previous visit. This time I simply wanted to enjoy the city’s ambiance. I visited the waterfront, but other than attending the conference I mostly enjoyed various Seattle restaurants and shopping with others who were attending the conference. I had dinner with MadCap CEO Anthony Olivier and Vice President of Product Development Mike Hamilton. I went on a pub crawl organized by several Australian conference attendees. And I had a lot of fun discovering places in the city with my friend and colleague, Lauren Anthone.

The conference was held at the Westin Seattle, and I stayed on the 42nd floor. The view and the perspective of weather were fantastic. At one point, I could see a heavy snowfall from my room. I called Lauren, who was waiting to meet me at street level. I asked what she thought of the snow. She was seeing only rain, so the snow never made it to the ground.

Some say that I was hallucinating. I’m not mad! It was snowing, I tell you!

Conference sessions

Some of the sessions that I attended were related to tools such as Flare and XMetal. I also spent a day at the vendor expo, working with my MadCap colleagues. I had the opportunity to talk with existing and prospective MadCap customers.

I attended the following sessions related to methodologies and best practices.

Introduction to DITA (Tony Self, pre-conference)

Right now, the hottest topics in our industry seem to be social media and the Darwin Information Typing Architecture, or DITA. So as we move toward collaborative work environments, we’re also moving toward more structured writing.

Although I have attended a class or two on DITA-enabled tools, extensively studied the DITA architecture, and created DITA content, I had never had formal, tool-independent training on the DITA standard. A three-hour, interactive DITA course led by Tony Self was just what I needed. Tony is one of the founders of HyperWrite in Melbourne, Australia.

Tony made a solid case for DITA adoption, including its strengths as an efficient, automated methodology for content reuse and single sourcing. He covered the basics of structured, modular writing, included an XML refresher, and led us through the specifics of DITA content creation.

We also discussed project and process planning for DITA implementation. Like content planning for any project, DITA requires modeling and information typing. You especially need to determine whether the basic information types (concept, task, and reference) are sufficient for your needs or whether you need to specialize.

DITA requires paradigm shifts. For example, in traditional help authoring, we create linked topic relationships using various methods. In Flare I sometimes assemble pre-determined Related Topics lists. More often I create a list of concepts, insert concept markers in topics, and let Flare build dynamic lists based on concept relationships (See Also lists). Tony pointed out that when you create DITA content, you should avoid linking because it adds context. DITA is designed for truly modular, standalone pieces of content, so relationship tables control the linking aspect behind the scenes. This puzzles developers who are used to traditional ways of controlling the linked structure, so it may take some mental adjustment.

Tony Self is a leading industry expert and an engaging instructor. He’s also a great person. I came to know him in a separate context when I attended a pub crawl organized by Australian conference attendees. Now I picture him draped in the Australian flag and leading us in the “Aussie, Aussie, Aussie” cheer.

The Google Chrome Comic and Visual Communication (Scott McCloud, keynote)

I am a fan of comic books as a learning tool. Apparently Google shares my enthusiasm.

The opening conference session featured Scott McCloud, author of Understanding Comics. Scott describes himself this way:

Depending on who you ask, I’m either comics’ leading theorist or a deranged lunatic…

In an interview with WritersUA President Joe Welinske, Scott talked about the process of creating the comic book that describes the technical aspects of the Google Chrome browser. He also discussed how comics offer an alternative way to tell a story, even in a business context.

When friend and colleague Carolyn Kelley Klinger and I began working together at the National Cancer Institute, our projects involved software applications that supported genetics research and terminology. Carolyn asked SMEs for a book that was accessible to non-geneticists, and they wholeheartedly recommended The Cartoon Guide to Genetics by Larry Gonick. I came to appreciate this mode of learning and became addicted to the rest of Gonick’s Cartoon Guides. Those guides are a great way to learn complex, scientific subjects. I now have a collection of them.

User-centered Design of Context-Sensitive Help (Matthew Ellison)

When I use software and expect to find useful, context-sensitive help (CSH), I often find that the result is perfunctory at best. Although my software utopia prominently features embedded help, I realize that CSH, when used effectively, can be a user’s best friend.

Matt Ellison traced the history of CSH from WinHelp to the Office 2007 ribbon and super tooltips. He provided varied usage examples, past and present.

One of the better examples (in my opinion) of a CSH landing page included these elements:

• method of access
• overview of the window’s purpose
• conceptual information supporting usage
• specific window features and how they’re used
• links to related topics

Matt emphasized that, regardless of what we include in CSH topics, we need to keep the user in the task flow. As he pointed out, users typically consult the help when they are already engaged in a task. Thus, CSH should provide “quick and easy answers to mid-task questions.”

Here’s the first list expressed as questions:

• How do I open this window?
• What’s the purpose of this window?
• What do I need to enter in this field?
• Why do I need to provide this information?
• What does this feature do?
• Where can I find more information?

Matt provided many examples of varied approaches, showing how we sometimes provide too much or too little information, rather than giving users exactly what they need at the moment they seek help. He suggested that CSH topics should enhance task performance with a combination of conceptual and reference information, rather than procedural. One of his key points is that we should “focus on answering likely questions rather than documenting the application.”

Architecting UA Topics for Reuse (Michael Hughes)

Although savvy doc teams have established methods of reusing content for years, a lot of cutting and pasting is still going on. I see this first-hand when I work with new clients, and I try to steer them toward modeling and analysis for reuse. I have used various tools and techniques over the years to implement and support reuse, so I am now learning about how DITA supports reuse.

This session by Mike Hughes was a useful extension of Tony Self’s pre-conference workshop. But even though Mike used DITA examples, the principles he discussed are applicable to any development environment.

After providing an overview of content reuse and its benefits, Mike provided examples of reuse in different media and different documents. I appreciated his emphasis on using semantic markup to separate content from presentation. DITA, for example, uses uicontrol in lieu of strong to bold UI elements.

Mike says

Don’t tell me what it should look like. Tell me what it is.

Mike also reinforced Tony Self’s point about linking topics, saying that we should “avoid embedded links that create dependencies.” To achieve truly modular reuse, we need to separate content, structure, and relationships.

Techniques for Reviewing a User Interface (Rhonda Bracey)

As writers of documentation for software products, we often work with a variety of user interfaces. Well-designed interfaces make our job easy. Others make it downright difficult. How many times have you searched for euphemisms to describe software “features”? How often have you struggled with procedural steps that became needlessly complex because you were forced to explain UI elements that were not intuitive?

I have often worked with software development teams to provide usability input and suggestions for improving a user interface. I usually create a spreadsheet report that is tailored to evaluating the application. Rhonda Bracey, owner of CyberText Consulting, has done better. She has developed a useful checklist that gives us a repeatable evaluation strategy.

For starters, Rhonda reminded us that our words aren’t the only thing that should communicate. She quoted a post from Chuck Martin on the Help Authoring Tools and Techniques (HATT) group from January 2008:

‘Communication’ encompasses not only the words created for manuals and help systems, and not even the words used in the interface, but the interface itself, and the way it does—or doesn’t—inherently communicate its functionality.

Rhonda recommended that a tech comm professional start evaluating the interface early in the development cycle. We should check for clarity, consistency, and conciseness, while helping to reduce confusion. This includes the following categories:

• Design elements: Are interface elements well placed? Do they contribute to the overall flow?
• Text elements: Are labeling and wording consistent in such things as title bars, status bars, menus, icons, buttons, and system messages?
• Link elements: Do link mechanisms such as menus, sidebars, breadcrumb trails, and URLs work?
• Visual elements: Is the design coherent, or do some elements have a jarring effect?
• User actions: When you interact with a UI element, is the result what you expected?
• Performance: Do you spend a lot of time waiting for a system response?

Rhonda provided suggestions for tools that aid the process of UI evaluation, but she reminded us that the eyes and brain are our best tools.

• Read Rhonda’s related article in UX Matters
• Download Rhonda’s checklist (PDF) or buy an editable version here

Back to top

This book review was originally published in the May 2008 edition of the STC Technical Communication journal.

Information about the book:
User Interface Design for Mere Mortals
by Eric Butow
2007. Boston, MA: Addison-Wesley
ISBN 978-0-321-44773-9

Every technical communication specialist can benefit from having a solid foundation in the principles of usability, user interface (UI) design, and usability testing. Even if the word usability is not in your job title, some aspect of your daily work contributes to the usability of the products that you support. 

Product design and development teams increasingly recognize the value of integrating a usability strategy into their overall processes. They understand that such integration ultimately leads to more satisfied customers. Regardless of your team role, the adoption of a usability strategy requires that you understand how usability practices fit into the big picture. 

You will find no shortage of learning resources on usability research, UI design, and usability testing. As interest in these subjects grows, so does the available library of books and online resources. So if you want to increase your knowledge, where do you start? 

User Interface Design for Mere Mortals is an excellent starting point. Author Eric Butow has written a timely, comprehensive resource that serves as both a usability primer for beginners and a source book for more seasoned professionals. Regardless of your experience, the book grounds you in the history, philosophy, models, processes, and challenges of the usability profession. Butow highlights the major contributions of experts who have shaped the profession, drawing from the works of such authors as Joseph Dumas, Ginny Redish, JoAnn Hackos, Alan Cooper, Robert Reimann, Donald Norman, and Carolyn Snyder. 

Butow’s book is not a tool-specific, step-by-step guide to designing interfaces. It examines both desktop GUI and web design from a big-picture perspective, starting with the four design imperatives: ethical, purposeful, pragmatic, and elegant. You set goals for your design and have users test it with such techniques as paper prototyping. 

To reinforce the design process, Butow provides a case study in Chapters 3 through 9. The fictitious company, Mike’s Bikes, originated in Michael Hernandez’s Database Design for Mere Mortals (Addison-Wesley, 2003). Butow’s case scenario revisits Mike’s Bikes after a three-year growth period, when the company wants to redesign its web site to meet its changing customer needs. 

In the first installment of the case study, the author presents one of the biggest challenges that usability professionals face: selling usability to company management. If you’re facing this challenge, you’ll find the chapter “Making the Business Case” a great resource. This chapter explains everything that you need to do to champion your cause, including how to communicate the benefits of good design to company stakeholders, how to identify the goals of both users and stakeholders, and how to calculate the company’s return on investment (ROI). You’ll also learn how to integrate the Usability Engineering Life Cycle (UEL) into your product development cycle. Showing that you have a ready-made process can help you to convince management that usability integration is a necessity. 

Butow underscores the importance of documentation and training materials as the “first line of customer support” (p. 96). He counts technical writers among those professionals who provide a usability service, stating that “most technical writers are passionate about making printed or online documentation as easy to read and use as possible” (p. 48). The section “Good Documentation Design” in Chapter 4 provides a useful overview of the documentation planning and development cycle. 

A recurring theme throughout the book is that satisfied users (customers) are the main determining factor of successful UI design. Chapters 5 and 6 focus particularly on users. 

Chapter 5, “How Users Behave,” explores the psychology of users and user actions. This chapter categorizes users by psychological type, deriving its categories from sources such as the Myers-Briggs Type Indicator (MBTI) and the four primary temperaments first established by David Keirsey and Marilyn Bates and later extended by Bryan and Jeffrey Eisenberg: methodical, spontaneous, humanistic, and competitive. A central idea is how users form a conceptual model on the basis of “life experiences, beliefs, and other methods that [they have] built up over the years” (p. 127). They use this model to guide them when trying to perform a task. 

The chapter “Analyzing Your Users” continues with the focus on users and user goals. Here, Butow emphasizes the Goal-Directed Design Process of Cooper and Reimann, which follows a five-phase process: research, modeling, requirements, framework, and refinement. The modeling phase is the point at which the design team creates its user models, or personas, on the basis of “groupings of user goals, motivations, and behavioral patterns” (p. 144). The latter half of the chapter emphasizes ways to construct and evaluate personas on the basis of careful user analysis. 

User Interface Design for Mere Mortals closes with a comprehensive chapter on interviewing users, conducting usability testing, and presenting testing results. Butow gives you a wealth of advice to get started, again drawing from many established and authoritative resources on usability testing. 

As technical communication specialists, we should all aspire to create an effective user experience, regardless of our role on the product development team. User interface design for mere mortals is a valuable, comprehensive resource for usability practitioners at every level.

Back to top