Expanded Text vs. New Topic--
When should you use expanded text (type 2 link) versus going to a new topic (type 3 link)? (See 10/26 blog for more on types of links.) Normally, we think of expanded text as applying to lists like menus--showing subchoices-- or to term definitions--expanding the paragraph to include the definition of a term used in that paragraph.

I have seen expanded text used effectively, however, to open up larger discourse elements, such as procedures or tables. In these cases, the alternative could easily have been to link to a new topic page. Let me give an example where I think expanded text could be the more effective alternative.

Let's say you have a help topic that is about Configuring the Widget. And let's say that there are three distinct procedures that relate to configuring the widget: Procedures A. B. And C. Furthermore, let's say that you're not done configuring the widget unless you've done all three.

You could certainly have an overview page that linked to separate topics for procedures A, B, and C. And there would be NOTHING WRONG with that. But you could also show the 3 procedure titles as type 2 links, that is, links that expanded the text to display the procedural information on the same screen. Some advantages of this approach would be:

• User stays in the same topic in the help--less chance of cyber-disorientation.
• User can expand all three topics and read a coherent description of the uber-procedure.
• User can print the uber-procedure as one document.
• If an expanded link changes color as a visited link, user gets a visual aid in tracking his progress through the uber-procedure.

Some disadvantages could be:

• Screen could get unmanageably long.
• Accessing just a sub-procedure, for example, just procedure B, from a search or index would not be as precise.

This weighing of advantages and disadvantages in determining when to use a specific pattern is called Claims Analysis, and is an important part of applying pattern language to user assistance design. (see 10/27 blog for more about pattern language.) It avoids hard-fast rules of "do it this way" in favor of more contextual guidance for the user assistance writer, more like: "In these conditions, consider these forces."

User Assistance Behaviors--
In the upcoming February issue of SIGCHI's Interactions, I have an article entitled "A Pattern Language for User Assistance." The gist of its premise is that we often have style guides for technical communications that describe how information is to be presented, e.g., how elements in the GUI should be referenced, how procedures should be worded, etc., but we don't describe how the user assistance should behave. In the article I say:

Best practices in user assistance can no longer be developed and communicated in terms of "These kinds of words need to be displayed this way;" rather they need to be communicated in terms of "In these scenarios, the user assistance needs to behave this way."

In short, we need to treat the GUI and user interaction aspects of the user assistance itself in the way UI designers treat their GUIs and interactions.

Link Behaviors
In yesterday's blog I identified the following four kinds of links that can appear in user assistance:

1. Initiate a popup
2. Expand the text being displayed to reveal additional text
3. Jump to a new topic and display it in the current pane--replacing the current text
4. Jump to a new topic and display it in a new window or pane--keeping the current text in tact

Guidelines for user assistance writers should include when and how those links should be used. For example:

Definition links occurring within a paragraph or procedure should use a type 1 or type 2 link. If it is likely that the user would print the topic, consider using a type 2 link (expanded text). If the displacement of text could be disruptive or obtrusive for some reason, favor using a type 1 link (popup). If both types of links are used, use affordances or pliancies that differentiate between the two.

You may wish to be more specific in order to maximize consistency across writers, but the point is that the behavior of the user assistance needs to be part of the style guide or defined patterns. And those defined behaviors are not based on principles of composition, rather on principles of human computer interaction and usability.

The user assistance writer's reference bookshelf needs to look more and more like the UI or UX designer's bookshelf. How does yours look?

Hyperjacked!!--
There is a thin line between the skillful interconnection of related information in an online help file and the fragmentation of the user's cognitive flow. Some user assistance authors seem seduced by a converse Cartesian credo of sum ergo tripudio, I am therefore I link. The result can disorient the users by forcing a cyber version of attention deficit disorder upon them by jumping them around too casually--what I term hyperjacking them. The following are some guidelines to consider:

Signal what kind of link the user is about to take.
There are four ways the user assistance can respond to a link:

1. Initiate a popup
2. Expand the text being displayed to reveal additional text
3. Jump to a new topic and display it in the current pane--replacing the current text
4. Jump to a new topic and display it in a new window or pane--keeping the current text in tact

I was in a help file yesterday that had links of types 1, 2, and 3, yet used the same presentation for all three. In one instance I clicked on a term in the middle of a paragraph and a definition popup appeared; in another situation, that same scenario jumped me to a new topic page. The solution is to provide different affordances (how the link looks) or pliancy (how it changes when moused over) behaviors to signal to the user what kind of response to expect from clicking on a link.

Don't break chunks into fragments.
In Information Mapping (R) lingo, don't jerk someone out of the middle of a block and send them to another map. Blocks such as paragraphs, tables, and illustrations should use only type 1 and type 2 links (as defined above). Consider the following scenario I experienced recently:

1. I clicked on a link that was the title of a procedure (out of a list of 3) and it expanded to display the steps.
2. I then clicked on a term in one of the steps (expecting a definition popup) and was hyperjacked to a new topic. It looked very involved and had lots of other links and I decided it was much more of a commitment to the term than I was willing to make, so I clicked the back button.
3. I was returned to the page I had just come from, but it was in the default state with all the expanded text collapsed. I wasn't really sure which procedure I had been in when I took the original link.

Breaking up the user assistance in the middle of a unit of discourse (sentence, paragraph, etc.) moves the user into a new thought before you've let them get through the current one. Decide what your smallest unit of discourse is going to be. Info mappers would probably define this as the block. For non-mappers, I recommend the paragraph, procedure, and table as being unbreakable units of discourse.

Tomorrow I will discuss guidelines for when to employ which type of link behavior in a help file.

Stay posted!

Knowledge Harvesting--
My big aha came several years ago when I was documenting a predictive dialer product (software/PBX switch that automatically makes outbound calls for a call center based on calling lists, and operator/outbound line availability). You know, that nasty technology that lets annoying telemarketers and collectors bother more people than if they were looking up numbers and dialing them manually.

I had to document the screen that let the system administrator set the "busy call-back time" i.e., how long the system would wait until before it redialed a number that was busy. My online help was flawless: it defined the parameter, gave the minimum and maximum values, and explained how the spinner control changed the value: "click the up arrow to increase the call-back time; click the down arrow to decrease it." Took it to a usability lab and sat poised with victory cigar in hand just waiting for the positive feedback that would say "Light 'em if you've got 'em."

Interesting turn of events, however. The parameter was pretty well named apparently; no one really needed the definition to figure out what it meant. The whole up arrow and down arrow thing seemed to work pretty well; the users figured that one out without the help. The min and max values became pretty obvious when the numbers quit going down or up.

Even so, users still went to help. What they wanted to know was, "What's a good number?"

You know, there's a reason it's sometimes called the "anything but help" button. Mine certainly fit the mold.

There is a happy ending...
I found one of our customer consultants, the folks who went onsite and helped customers tune their systems, and I asked him what a good number was.

"Ten minutes," he said. "You know there's a warm body there and you don't want to let him or her slip away."

I followed up, "Why would you make it higher or lower?" After all, there had to be a reason for the spinners that allowed the system administrator to change the parameter setting.

"Oh, I check the daily reports," he said. "If the line utilization rates are low, I change the busy call-back time to make it higher--you see, I'm calling the same busy number too many times and I'm wasting an outbound line. If the hit rate starts going low, I decrease the busy call-back time, I'm letting the live bodies get away by not calling back."

OK, there's a lot of fuzziness here, no hard and fast algorithm, but some real meaningful heuristics. That's what the users were looking for: guidance.

The Challenge
Writing up what he told me was easy, any half-dead Information Mapper (R) could do the If/then table on the way to post-op. Even anticipating the question should have been easy: any time a user is asked to set a parameter or make a decision such as enable or disable, they will want some guidance. Even the pattern was obvious: State a typical starting point, describe considerations and impacts for changing, and point to system outputs that can give you feedback on the impact of the decision made.

So why didn't I put it in the help from the get-go?

I wasn't tied into the source of application expertise--I worked with developers primarily. I'm not being snotty; it's unfair to expect that experts in C++, Java, and database creation to also be experts in running a call center. I had to leave my social and disciplinary comfort zones and seek partial truths from segments of the business I was not used to dealing with.

The challenge, then, is threefold:

• Identifying the kind of information the user will need
• Designing how to route that information from the Content Management System
• Finding the source of the information in order to articulate it and get it into the CMS

The third bullet is why I emphasize that a robust user assistance system has elements of a Knowledge Management System. It is the harvesting of useful content from experts, when that content is often loosey-goosey (aka "fuzzy") and tacit.

The upcoming STC conference in May will include a conference-in-a-conference called the Knowledge Management Institute. Larry Todd Wilson will be doing a presentation on Knowledge Harvesting--I highly recommend it for any UA architect or content developer who has to document complex applications where the guidelines users seek cannot be culled from the product technical specification.

Wireframing--
I don't think that wireframing user assistance is probably a common skill among UA writers, since the user interactions are largely defined by the authoring tools. I certainly never routinely did wireframes until I became a UX designer and was designing the user interface for the application. As UA becomes more integrated into the user interface, however, and as user interactions within the UA become more complex or application-like, e.g., Wizards, wireframing should become a routine activity for UA Architects and Information Designers.

The purpose of the wireframe is to show the layout of the elements within the User Assistance Interface, describe their content or presentation rules, define how the user can act on them, and how the system should respond to those allowable user actions. The wireframe is, in essence, the blueprint that communicates the following:

• Tells the UI developer how to present the UA--in all of its possible states
• Tells the technical writer what kinds of content needs to be provided
• Tells the QA tester how the UA interface behaves

What the wireframe does NOT show is the actual content delivered. It might not even define the source(s) of the information--that might be better described with an information flow diagram.

Tool Talk
Wireframes can be built with a number of tools: Visio, special wireframing software such as Axure (see www.Axure.com for a free 30-day download of a very useful wireframing tool), or even PowerPoint. Using the action buttons and hyperlink tool in PowerPoint allows you make a fairly robust demo/prototype of how the user interactions would work.

For the project I am doing now, I first used PowerPoint to experiment with user actions and system responses, using sample content to do reality-checking on the user experience. I then did production-level wireframes in Visio, using placeholders and lorem ipsum text to illustrate content. I used the Software/Windows and Dialogs stencil to show the UI and the UA components. For each view or state I used two pages, one to show the UI wireframe and a second one to document the elements and interactions. On that second page I used an object table that has the following columns:

• The callout number I use on the wireframe for that element
• The name of the element
• The user action
• The system response
• Comments

I have created a row with those elements that I have stored as a widget in my custom stencil. I drag that widget onto the wireframe, document the element, and then cut and paste the row to the object table I am building on the following page. I have found this to work better than what I used to do, that is, try to document the wireframe with notes on the same page as the wireframe. That just got way busy and limited the information you could put in the note. The down side is that you have to have two pages in front of you to understand the page's look and interactions.

A tool like Axure has a more friendly approach, allowing you to see an element's notes while still viewing the wireframe, but it has the same downside as above if you want to see the notes of several elements at once. It has an additional limitation of not letting you edit your notes if you are viewing multiple elements (in its Word document output). This is a pain if you are editing your notes for things like consistency, e.g., did I hyphenate single-click in the other notes or not? Hey! We're tech writers; we worry about stuff like that :-)

Ontology and User Assistance Architecture--
User assistance architecture has more to do with elements: how they are presented, organized, and behave--rather than the actual content within a specific instance. Ontology is the inventory, so to speak, of what elements you have at your disposal as an architect.

I am currently working on a wireframe for an embedded help pane and must decide what can go into or be accessed within that pane. The following is a sample ontology for such a pane:
Search: A way for the user to enter search criteria and initiate a search
Search Results: The list that the search returns
Links: Interactive text that navigates through content
Buttons: Command devices that initiate action
Headings: Elements that describe associated content
Multimedia: Elements such as graphics, e-learning, show-me demos
Documents: Large prewritten discourses such as user guides in PDF
Contacts: Tech support or other users who can help solve a problem
Knowledge Base: A database of known problems and recommendations
Information Blocks: Information displayed in small chunks. Blocks can contain several sub-types of information objects. It is useful to identify them, since you may want different types of information to be displayed differently. The following is a breakdown of possible information blocks:

Information Blocks
Definitions: What a term means
Purpose Statements: What a screen or module is intended to do
Guidelines: Higher order information a user needs to know in order to apply the screen or application within a user-goal context. For example, what are the impacts of enabling or disabling a feature or what should be considered when choosing among radio buttons A, B, or C.
Procedures: Sequence of steps to accomplish a task
Orientation: What impacts the current screen/task; what is impacted by the current screen/task

Food for Thought
As technical communicators, we are often drawn to procedural information as the core of user assistance. The sophistication of user interface design practices, however, often obviate this kind of information. See Procedures: the Sacred Cow Blocking the Road? . Consider this when prioritizing what types of information to present at the highest levels.

Progressive Disclosure and Hierarchy of Information
I am currently working on a wireframe for an embedded help pane and wrestling with the real estate constraints and information-prioritization issues that come with megabytes of information vying for a surface area roughly the size of an envelope.

The obvious solution is to not show everything at once in the panel, but to use the pane as a gateway into the content. Allow the user to navigate into and through the content by progressively disclosing greater detail or related topics.

The UA architectural issue is how to categorize and prioritize information so it can be appropriately displayed and disclosed. This requires that a taxonomy of presentation tiers be defined and that an ontology of pane elements be defined and mapped to the presentation tiers.

Presentation Tiers
Start first by understanding how many layers of presentation options you will use and rank them into tiers. The following is an example of a presentation tier taxonomy:
Tier 1: Information that is displayed upon initial appearance of the pane without any interaction on the part of the user.
Tier 2: Information that is displayed within the original presentation by expanding the content. In other words, the pane's initial information remains, but new information is inserted. For example, a definition could be tier 2 information; the user clicks on a term in the text and the text expands to include the term's definition.
Tier 3: Information that replaces the information in the original pane. In essence, the pane's content is replaced with new content. One could slice this even finer by having Tier 3A that replaces a entire pane's content and Tier 3B that replaces just a section within the pane.
Tier 4: A new window is opened to display the content; the original embedded help pane stays intact.

Ontology of Elements
I just love having the opportunity to use the word ontology :-) I can only hope that I am using it reasonably correctly. I use it in a broad sense to mean what is the furniture, so to speak, you can put into a user assistance pane. The ontology will contain interaction devices such as search criteria entry fields, navigation devices, such as links, and information elements, such as headings, definitions, procedures, multimedia, etc.

This is the part I am working on now, defining that ontology and mapping the elements to their appropriate presentation tier.

Keep posted.

Community-building User Assistance
For a great example of community-based user assistance, sign up for Trillian, a cross-application instant messaging client (www.trillian.cc). I did so and then went to their help to find out how to add a contact. I entered "add contact" in their search engine and was taken to a forum thread where a user had posted instructions for adding a client. The post included the user's picture!

Granted, it's an instant messaging site--they are all about community--but it's a technique that stodgier apps could also apply.

Why Incorporate Community-based User Assistance?
I'll be real honest, something seems a little topsy-turvy at first about letting users write (or least contribute to) the user assistance. Aren't we supposed to know more about our applications than our users do? (let it sink in, two...three...four) Says who?

There is an underlying assumption that people who build an application know more about using it than the people who use it. That is not always the case. Users have more contextual knowledge than the inventors do in many cases. Add to that the fact that user assistance is typically written by technical communicators (that would be us) who are often isolated from both the inventors and the users. At best, we typically document as designed whereas users understand as built and as used.

I was at a presentation some work colleagues of mine did at Georgia Tech last week where our Chief Information Architect made the point that a successful product should build communities as a way of raising the cost of leaving the product. He struck a metaphor of selling one's home and moving. It's not just the house you would be leaving, it's the community and all you have invested socially in its members and institutions. Products that build communities encourage loyalty. User assistance has a unique perspective to bring to community-building: getting the user in touch with others who have met and solved the same problem the current user is struggling with.

User Assistance as Community Builder
A user assistance architecture that was designed to act like a knowledge management system would include community building capability--that is, ways to link the users to experts other than the static published documentation set.

Look at how Amazon.com, a retail site, does an excellent job of community building (thus providing a dynamic user-to-user user assistance).

• User reviews
• People who bought this book also bought these books...
• User lists of favorites around a given topic being currently viewed

At the WritersUA conference this year in Palm Springs, I sat on the pundits' panel that had to offer up predictions of where UA was heading. One of my predictions is that user assistance would incorporate user-content accommodations like Wikis. This would be one way for complex applications to create communities of practice around their products. Other community-building opportunities to incorporate into the user assistance framework would be WebChat, links to relevant threads within a user forum (based on the topic or search question at hand), and links to external sites, such professional associations, that could provide information about the topic.

Content Management vs. Knowledge Management
In a meeting yesterday, I noted that I thought user assistance architecture was evolving to a fusion of content management and knowledge management. Later, I wondered what the heck that meant. What exactly is the difference between the two and what would something act like if it were a fusion of the two?

A somewhat simplistic yet illustrative analogy comes to mind--
Content Management : Knowledge Management :: Food Warehouse : Grocery Store

There are many flaws in this analogy, but let's work it for awhile as if it answers the question. A content management system (CMS) focuses on storing and retrieving content, predominantly in large boxes known as documents. A CMS is essentially a storage and redistribution channel. The main users of CMS are not the end user of the content in many cases, but writers and publishers who create multiple documents by rearranging content or distributing that content in different formats, e.g., PDF, paper, online Help, web pages, etc.

A knowledge management systems (KMS) focuses on creating content and delivering it within the context of specific user needs. There is also a stronger social component in a KMS. What does the grocery store have that a food warehouse does not? Experts like butchers and produce managers. Grocery stores also have fellow shoppers who can help. Another big difference is that warehouses lack user context, Cheerios are as likely to be stored next to ketchup as anything else. Context in a warehouse has more to do with storage size, inventory turns, and the like. In a grocery store, things get stored next to like things for ease of price comparison or next to related things. No food warehouse would ever store bananas and vanilla wafers next to each other, whereas that arrangement is common in grocery stores for obvious reasons.

Next week, I will try to land this analogy home with a more detailed examination of how it applies to user assistance architecture.

Defining User Assistance Architecture
I have avoided the job title of architect for several decades now, but it has eventually overtaken me. So now I must ask myself what do I do that's different from being a technical communicator? In a classic sense of architecture (as in designing buildings) architecture means defining the structure and form for places that accommodate human activity. OK, that seems like a good starting place. So a User Assistance Architect is someone who defines the structure, organization, and delivery methods for presenting user assistance, i.e., information and instruction that supports user activity within an application.

As an architect, I need to be less concerned with the detail of the content and more concerned with the types of information that content must contain, when to present it, and how to best let the user access it.

So how does one go about doing this? The initial methodology I am using in my current task is based on use cases. Bear in mind that I have been brought into an environment where there are mature products with lots of user assistance in a variety of forms and locations already in existence. My chosen role right now is more of User Assistance Anthropologist, i.e., discovering and cataloging what exists. Even though this puts me more in a deconstruction mode, I think the approach would work equally well in a construction mode, i.e., where a product or product suite were being built from scratch. I say this, because use cases are primarily design tools anyway, and my use of them to analyze an existing product structure is more the exception.

I have chosen a representative product and I am populating a four-column table with:

Use Case * Scenario * Information Requirements * UA Channels/Patterns

I am in the process of reviewing product documentation, interviewing SMEs and writers, and then trying to fit what I am learning into this table. Although the initial purpose is to capture current state, I imagine that the same structure will be useful to define future state as well.

So far the approach is working well for me--it provides a structure to help me start to unpeel the onion in manageable layers. Best of all, it lets me collect information in the random way information likes to emerge but store it in a way that lets structure start to emerge.

I will discuss this methodology in more detail in later blogs.

Modes of User Assistance
One can think of user assistance as falling into one of two modes: pulled UA and pushed UA.

In pulled UA, the user takes action to summon or access the user assistance.
Examples of pulled UA include:

• Manuals
• Help files (accessed by clicking on Help in the menu or a Help icon)
• What's this?
• Search

In pushed UA, the system detects a situation and provides assistance proactively. Examples of pushed UA include:

• UI instructional text that is part of the static UI display, e.g., examples of date formats next to date entry fields
• Field and control labels
• Default instructions in dropdown lists, e.g., "Select carrier" as the default selection in a dropdown list for selecting cell phone carrier.
• Roll-0ver techniques such as tool tips (which can turn into pulled UA as the user comes to expect the technique and deliberately mouses over an object to get information about that object)
• Contextual embedded help
• Did you know? or Tip of the day messages
• Context-sensitive help activated by clicking an icon
• Linked help, e.g., Tell me more... links that expand on information provided in the UI.

Pulled UA requires that the user be in a state of explicit ignorance, that is, the user does not know something BUT is aware that she does not know that something. It also requires that the user be able to articulate, at least in general terms, the question she wants answered. For example, a procedure on How to make an unordered list is going to be accessed only by someone who knows that lists can be bulleted for better effect AND who would know that such a list is called an unordered one.

Pushed UA can be very effective when the user is in a state of tacit ignorance, that is, the user does not know something and is also unaware that she does not know it, or that it even exists to be known.

Designing and writing pulled UA require attention to content organization, taxonomy creation, indexing, and good search capabilities. Designing and writing pushed UA requires that the user assistance be more integrated with the application and act more like part of the product.

Categories of User Assistance
By its very form, the phrase user assistance implies the existence of a tool, i.e., the thing used. The existence of a tool implies an application or goal, i.e., what the user is trying to accomplish with the tool. In other words, the existence or a Word Processor implies the user's need to create a document. So user assistance is help in using a tool to achieve a goal. In this sense, user assistance can be divided into two main categories: (1) How to use the tool and (2) How to use the tool to...
The first is very tool-centric and focuses on the rules and manipulations of the application itself. Good user-experience design minimizes the extent to which this kind of UA is needed by making these manipulations and interactions self-evident, but some degree of this assistance will be required in most applications. How to enter a summation formula in Excel would be an example of How to use the tool user assistance.
The second category of UA, How to use the tool to..., is more user-centric and focuses on goals and problems within the user's context. Showing someone how to use Excel to do a budget would be an example of How to use the tool to... kind of UA.

Levels of User Assistance
At its most basic level, UA is discourse that explains something and can be delivered through channels that are more or less detached from the tool, e.g., manuals or compiled help files. As it becomes more advanced, it becomes more interactive and integrated with the tool. Embedded help and bubble help are examples of more highly integrated user assistance patterns. At a more advanced level, user assistance acts like a Performance Support System and is highly integrated within the tool, e.g., a Wizard. At its most advanced level, it becomes the tool. For example, is spell-check a feature within a word processor or is it user assistance?

Metablog
Blogging is an odd activity. On the one hand, it seems absurdly self-centered, as if what the blogger has to say is of such importance it must be shared with the world. On the other hand, it is like the mutterings of a street vagabond: words said in public but listened to by no one. I rather hope it is more like the latter :-)

The Role of This Blog
I am changing jobs and taking on the role of User Assistance Architect in which I will have the fun task of "identifying tools, methods, and standards to integrate the content and delivery of user assistance, including documentation, help, e-learning, and training. " I will use this blog to reflect on and articulate my thoughts about user assistance as I take on this new challenge. I will deliberately avoid the temptation to publish well-thought-out papers, and use this space instead to put emergent thoughts out for my own reflection and for public scrutiny.

So if anyone wanders by this cyber vagabond and would like to comment on my mutterings, all input would be appreciated.

In my next entries, I will be focusing on defining user assistance and exploring its place in the broader field of User Experience.