Western Highlights: WritersUA 2009

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

Tagged as: Presentations