Instructional Text on the User Interface: Some Counter Intuitive Implications--
User assistance occurs within an action context (the user doing something with the application) and is almost always delivered in close proximity to the focus of that action, that is, the application it supports. When user assistance is displayed within the application as instructional text on the user interface, conventional principles of good information design must be modified to accommodate certain forces within an interactive user interface.

Consider the following assumptions. If you accept them, they are going to lead to some implications for UA design that might seem counter intuitive to some.

• The flow of focus by which users process information on a computer screen is the same as when they process information on a page. In English, for example, that would be left-to-right and top-to-bottom. In Arabic, for example, that would be right-to-left and top-to-bottom.
• Users within an application are motivated to take action, and their focus is easily drawn to action objects, such as text fields, menus, and buttons.
• Once the user's focus is drawn downstream in the focus flow, it is difficult to redirect it upstream. In other words, if something initially draws the user's attention to the middle of a screen, it is far more likely that they will continue going over and down as opposed to going back up. This is especially true if there are additional action objects downstream.

Example
So let's consider a simple application with a two-button radio button group, and you would like to explain the concepts needed to make the appropriate selection. An example I've used before is a report output dialog box that has the user select HTML or PDF for the output medium.

If you have an instructional design background or have been well-grounded in information mapping, your instinct will be to define the terms and give appropriate selection principles before you present the radio buttons. In other words, you will be inclined to put the instructional text above the radio button group. In a document that is removed from the action focus, it makes a lot of sense to introduce definitions and principles early in the document in order to prepare the reader/learner for what comes later. But if you accept the three assumptions I presented earlier, you will understand that the following scenario is what typically happens in a UI:

1. The user's focus is pulled almost immediately to the radio buttons because the user is motivated to act.
2. This jumping immediately to the buttons causes the user to leap-frog over the instructional text.
3. Once downstream of the text, the user does not go back and read it, even if unsure of what the buttons mean. The user makes a best guess and moves on (attracted by the next action object downstream).

I have seen this scenario played out in countless usability tests of form-based web applications where instructional text is placed at the top of the web page. The problem is exacerbated by the resultant appearance of seemingly a lot of words being presented as a dense block. Much the way that quantum physics says that dense matter bends space, I hold that dense text bends users' "eye rays" rendering dense text invisible. The user tries to read it but at the last second their eye rays get deflected and they see the action object instead. (OK, the physics is a little flaky on that one, but you get the point.)

Implications
When putting instructional text on the user interface, apply the following principles:

• Divide dense instruction up by action objects, and put the appropriate text in close proximity to its respective action object.
• Put the text next to the action object (in the downstream direction preferably) or just below it.
• If the text is too long, and this orientation disrupts the screen layout for the action objects, for example disrupting the grouping of a radio button group, provide a link that opens a pop-up or dynamic pane. I have seen links be very effective when phrased like an FAQ.

Instructive Labels--
I should have learned by now not to trust my instincts. Instincts are often the manifestation of programmed learning, which means that our creative and critical circuits have been turned off. That's why collaborative teams are so useful; members can challenge each other's programming.

Huh?

I'm working these days on a team designing an online, interactive workbook that helps a network administrator plan how to install and deploy a security appliance. The workbook has three purposes:

• Advise the administrator about some decisions that need to be made
• Provide a checklist at the end that lists the steps the administrator must go through (based on how he or she answers certain questions in the workbook)
• Direct the administrator to the correct deployment documentation (once again, based on how he or she answers certain questions in the workbook)

I wireframed an approach that I thought had great merit. (It turns out it had merit, just not GREAT merit.) A typical page asked whether the user would use the device in routing mode or transparent mode and was set up like this:

1. The page contained a short intro paragraph that explained the device could operate in two different modes and that the administrator had to designate which mode.
2. Two radio buttons were provided, labeled "routing" and "transparent".
3. Next to each radio button was a thumbnail diagram that showed a typical typography for that mode.
4. Next to each diagram was a description of when/why the user might want to select that mode.
5. Beneath that explanation was a link to provide more detail about the mode if the user wanted it.

//In my next post, I'll talk about why I rejected the design of explaining the required concepts before asking the user to select the mode. That's an entirely different topic.//

Step 2 is where my instincts did me in. It just seemed so right that a radio button group for selecting options should have the names of the options as labels. (Hence my lack of embarrassment--it's not one of those decisions that screams "stupid.")

Then one of the writers on the team asked one of those questions that just makes me go "huh!"

"Instead of labeling the buttons with the names of the modes, which we then have to go on and explain, can't we just label them as statements that get right to the main selection criteria?"

Example
Let's say you have a report output dialog box that includes selecting the output format. The two choices are HTML and PDF.

My instinctive approach is to have a radio button group with two buttons labeled HTML and PDF respectively. My user assistance instinct is to provide a tool tip or UI text that would elaborate on those choices, e.g., "Choose HTML to view the report online; choose PDF to have a printable version."

My colleague's suggestion in the first example would have the labels themselves say "I want to view the report online (HTML)." and "I want a printable version (PDF)."

Clutter or good user assistance? It depends. If you were going to take up screen text explaining the label (as in my first example), my colleague's approach is clearly better. In the second example, we have to make a judgment call about how well known the output labels of HTML and PDF will be. In an authoring tool meant to be used by tech writers--clutter. In a business intelligence application meant to be used by financial managers and analysts--maybe worth the screen real estate.

At any rate, it's always a question worth asking. Let your creativity and critical thinking challenge your instinctive approach.

Expert Guidance in User Assistance--
Those who read my ramblings in this blog on this topic, can read a more coherent discussion in my article in UXMatters. I've decided to make this topic my point of passion this year :-)

Stay posted.

Happy New Year--
And speaking of new year, the theme of the January issue of SIGCHI's magazine, Interactions, is "Help: User assistance and HCI." I have an article in that issue called "A pattern language for user assistance." I've posted a copy to my website, and you can link directly to that copy here.

I will be doing a presentation at the WritersUA conference in March on this same topic.

I have another article coming out next week in UXMatters. That article is called "User assistance in the role of domain expert." This is a topic I have discussed in this blog, and will include a practical example of a pattern language.

I will also writing a regular column for UXMatters called "User assistance: Putting Help in context." I will be drawing a lot from the material I experiment with in this blog (and benefitting from a GREAT editor, Pabini Gabriel-Petit).

Progressive User Adoption: More thoughts on building an adoption profile--
Before moving off the topic of laying out a suggested progression for user adoption, I would like to discuss the two main progressive adoption dimensions: efficiency improvement and feature adoption. In essence, efficiency improvement says, "There's a better way to do what you're doing." Feature adoption says, "You can do more things than you're doing."

Efficiency Improvement
The biggest challenge you face with efficiency improvement is that you are coming in low on the benefit/effort ratio. By that I mean that the user is already getting the task done and you're trying to get the user to invest immediate time and energy for a longer term gain. This ranks right up there with telling overweight people they need to diet and telling smokers they need to quit. In other words, don't expect the user community to hoist you on their shoulders and carry you in a display of triumphant gratitude. In this dimension, we are going to want to look at strategies that minimize the adoption effort, possibly embedding shortcuts and some degree of functionality within the user assistance itself.

Feature Adoption
Depending on your business model, increased feature adoption could be a real sweet spot for you. Even though there is still an increased effort required on the part of the user, the one thing you have going for you is being able to offer benefits the user is not currently getting. The dominant strategies here will be to show (illustrate or demonstrate) the new state and communicate the ease with which the user can get there (and cancel back out).

Considerations
When laying out your adoption profile, think about along which dimension you will be taking the user. If you are only going to improve efficiency and the user does not do that task very often--you might just want to let that dog lie sleeping, or at worst, give it a gentle nudge and move on.

The better payoff is along the feature adoption dimension; spend your time and creative energy there.

Progressive Adoption Principle 2: Establish an Adoption Profile--
The secret to progressive adoption is to stop thinking of adoption as a Yes/No state on the part of the user, rather think of it as incremental adoptions over a period of time. Map out the basic core features that would represent minimal adoption and apply principle 1 to those ("don't get in the way"). Next decide what levels logically lead the user through a comfortable progression pattern over time.

For example, in online bill pay, we decided it was too much to ask a user to start by turning off paper bills and having the system pay electronic bills automatically. They first had to build a trust in the system. The best progression seemed to be:

1. Get the bill in the mail and pay manually online.
2. Authorize getting the bill electronically but still pay manually online.
3. Authorize routine bills to be received electronically and payed automatically online.

Two elements you should consider when planning a progression profile are:

• Level of trust required. Plan a progression that allows the user to build trust with the system. Trust can mean a lot of things, trust you with my data, trust you with my SSN, trust you with my credit card number, etc. It can also mean I trust that all this work is going to get me what I want. For example, MS Excel's Chart Wizard lets you see how your data will be graphically displayed at each step in the process.
• Level of skill required. Move the user along incrementally from basic skills to get core value to more advanced skills to leverage greater value. For example, MS Word starts with a default template in place. Using templates should not be an initial requirement, but should be planned as a step that happens after the user has made the initial adoption. Steps along the skill dimension should be sized for easily managed progression. Don't make the user have to learn a lot to get more value. As long as the perceived increase in value is proportional to perceived effort to get there, you have a workable progression profile.

I will discuss concrete user assistance techniques that can be applied to support progressive adoption over my next several blogs.

Stay posted.

Principles of Progressive Adoption--
In my last blog entry I introduced the concept of progressive user adoption, moving a user further along in terms of the frequency of use, number of features used, or the depth of functionality (moving from basic to advanced). This week I will start to explore principles of progressive adoption, especially where user assistance can be involved.

Priniciple One: Don't interfere with core functionality.
Keep the basic tasks (the prime reason for the user being in your application) easy to do. This could be Clippy's fatal flaw—he intrudes when I don't need him, forcing me to get off task to dismiss him. His lame attempts to be precious do not make me want to kill him more, just kill him more slowly and in imaginative ways.

How do you apply this principle? For one, when the user assistance intervenes, make the intervention easy to ignore without action. If you force the user to dismiss the intervention, you are detracting from the core experience. Mirosoft Project does this fairly well. For example, if you add a resource to a task, an icon lets you know there is a tip. If you click the icon, a popup opens asking do you want to increase the work or shorten the duration? Based upon what mode you are in, it has already made the appropriate decision and has marked it as the default choice. If you just plow ahead and keep working, the popup goes away and the default choice stays in effect. So as a user, I get two opportunities to ignore the progressive help. I learn to ignore the tip icon when I know what the tip is about, and I can just keep working when I get the tip without having to select the default choice. I do have to click back into the desktop, however; it would be even better if I did not have to even do that.

Probably one of the most important dynamics in progressive adoption is "readiness," the user must be at a state that is ready to accept the change. Until then, coaching or coaxing the user to a new level of product use can detract from the quality of the core experience and you end up losing the user [insert clever fishing metaphor here—it's early in the morning and I'm too tired to do it myself].

So the bottom line in progressive user adoption is to measure all interventions against the yardstick of "Does this interrupt the core task?" If the answer is yes, change the intervention.

Progressive User Adoption--
I'd like to start a series of entries about the role that user assistance can play in what I call progressive user adoption. User adoption describes the rate that users will accept a new product or new technology. People who discuss user adoption usually mean it in the sense of the initial decision to accept or reject the technology or product as well as the ongoing re-enforcement of that decision. By progressive user adoption, however, I will be focusing on the tendency of users (or reluctance) to progress more deeply into the features, functionality, or frequency with which they use a new technology or product. Of partciular interest is why users' adoption curves typically plateau out at a suboptimal level.

Let me start with some concrete examples of what I'm talking about. Whenever anyone of us starts a new job one of the first questions we ask about the phone system is, "How do I dial out?" We learn what we have to learn in order to make the initial adoption decision. Fast forward several months (years) later and see if that person has learned to do a 3-way conference call (or in my case, even make a simple transfer). In many cases the answer is NO.

And how often have you had to edit a document someone did in Word only to find out that no style tags have been applied. All layout and typographic effects have be done with tabs, paragraph returns (sometimes one between paragraphs, sometimes two or three) and by manually bolding and changing text size to create headings? Why was this person not using the style tag feature that would have made the process so much easier and the output more consistent?

In short, why do people quit learning before they're done learning what they need to know?

Why Care?
Well, first off, why do we care about this premature leveling of the learning curve? If they've bought the software, why should we care how well they use it?

As is so often the case, the first question you need to ask is, "What's your business model?" More and more, due to e-commerce on the Internet, revenue around a product is transaction based. For example, I worked for a company that provided online bill pay software and the processing of the payment that went on behind the scenes. It made money everytime someone paid a bill with its product. The more bills someone paid, the more money the company made. Transaction-based products have a lot of skin in the game around progressive user adoption.

Of course, there is e-commerce, where user activity is directly related to revenue. Do you think Amazon.com wants me to stop shopping on their web site after I've bought my books? Do you think they would like me to progressively adopt them as my music and electronic gadget supplier as well?

And even non-transaction based applications have an interest in my progressive adoption of the features that give their product a competitive advantage or increase my satisfaction and loyalty. Nobody uses WordStar anymore, not because it did not produce good looking documents, but because it was displaced by GUI-based word processors that made it easier to adopt advanced features, such as style tags, automatic headings, etc.

And as we see Google and Microsoft moving into the web app space where revenue will be tied into usage, progressive user adoption will become critical in those kinds of applications as well.

So What's the Problem?
Having been involved in online banking and online bill pay applications, I have been very interested in understanding why users' adoption stops at less than optimal utilization of a product. The following explanation is based on observations made in formal usability tests, focus group research, contextual studies, and is supported by published research such as Everett Rogers' seminal work in Rogers, E. M. Diffusions of Innovations (4th ed.), New York: Free Press, 1995 and an interesting model called the Technology Acceptance Model, see Davis, F. D., Bagozzi, R. P., and Washaw, P. R. “User Acceptance of Computer Technology: A Comparison of Two Theoretical Models,” Management Science, 35, 1989, pp. 982-1003

In short, people quit learning before they're done learning for the following two reasons:

• They shift from a learning/exploration mode to a task orientation mode. When users can meet their initial goals, they stop exploring. Instead, they focus on doing what they came to do, e.g., paying bills or writing a report. In other words, they don’t look for ways to do what they don’t know they could do. I discuss this problem in general with why users abandon help procedures in a proceedings paper called "Procedures: The Sacred Cow Blocking the Road?"
• A reduced benefit/effort ratio. The benefit/effort ratio is less attractive for incremental improvement than for initial adoption. There is a big difference between “If I don’t learn how to make a phone call, I cannot get in touch with my essential contacts.” and “If I don’t learn how to transfer a call, I can’t pass an outside caller on to someone else in my organization.” The benefit side of the ratio is often diminished in the eyes of the user by existing alternatives that allow the user to reach a goal, although in a less efficient manner. In the call transfer example, the user can always give the outside caller the third party’s extension and ask them to redial that party directly.

What's Next?
I think that user assistance can have a positive effect on progressive user adoption if designed to do so. It can also have catastrophic consequences if done poorly. (I'm not making any specific references to Clippy here; I'm only saying.)

My next series of blogs will continue to explore how user assistance can be an asset to a company where progressive adoption advances the business model.

Stay posted.

Given-New vs. Analogy--
Today's blog is for die-hard writers who get a buzz from talking about rhetoric. No tools or technology today; I'm going through enough of that on the day job :-)

I was structuring a formal analogy the other day, you know--A:B::C:D (read A is to B the way that C is to D), and wondered what the preferred sequence should be. Should the new relationship be in the AB slot with CD being the relationship the reader is already familiar with, or should AB be the familiar relationship and CD be the one that is new to the reader?

I've always been a big fan of using a Given-New rhetoric when trying to explain complicated material. In that scheme you make the topic (subject) of the sentence some concept the reader is already familiar with, and you introduce the new concept in the predicate. Then the next sentence can take the predicate from the previous sentence and make it the subject, since it has now become a "given." The technique allows you to build up a knowledge base, so to speak, within the reader in small, manageable steps.

For example, let's say you had to explain DITA to a reader base for whom it would be a new concept. Watch how in the following text, the subjects of the sentences are concepts that are already familiar to the reader. Pay particular attention to the dance that ensues from a concept going from the predicate position in one sentence (where it was the "new" concept) to being the subject in the next sentence (because it is now a "given" concept). The following explanation assumes that the concept of structured writing is a familiar one to the reader.

A form of structured writing that has gained much popularity in recent years is DITA. DITA stands for Darwin Information Type Archictecture and is an XML-based approach to authoring. XML is the mark-up language that enables authors to share content across different platforms and among different documents.

You get the idea. This is a blog and that was a quick example, so don't edit me too critically on it. Like any horse, Given-New can be ridden to death and its overuse can leave your discourse sounding "sing-songish" and feeling mechanical. None-the-less, I have found that it is often a good technique for first drafts of paragraphs where I feel I have to move the readers across a rather large gap between what they already know and what they need to know.

But that logic didn't "feel" right to me when trying to put an analogy together; the order of New-Given seemed better within that device. For example, let's say I am trying to explain DITA topics to someone who is already familiar with Information Mapping. Which of the following analogies works better?

• Topics in DITA are similar to maps in Information Mapping.
• Maps in Information Mapping are similar to topics in DITA.

I think the first works better even though it is leading with the new concept and relating it to a given. Maybe because in context, it would appear in a discussion about topics, and, at least in that context, it would be the given topic.

But beyond that, I think there is something to be gained in an analogy by posing the strange relationship first and then grounding it in the familiar. It seems to be consistent with a principle I have noticed in instructional design: Students have no way to process a solution until they experience the problem. In other words, it's best to raise the question before providing the answer as an isolated fact.

Gap Analysis--
Sometimes we operate under the false myth that we must write user assistance for the lowest common denominator. I think this leads to bad help quite frankly. The better approach is to have a multichannel approach to user assistance and target channels toward the appropriate level of expertise for that channel.

I'm working on an embedded user assistance model (a dedicated help pane on the application UI), and this principle has suddenly clarified things for me. The issue came up, how far do we go with the embedded user assistance? My answer for embedded user assistance is, "Not too far." This channel is excellent for users that are almost smart enough to not need assistance. If the gap is large, other channels like elearning, tutorials, etc. are the appropriate place to deal with those needy ones.

In other words, it's OK to say, "You have to be this tall to ride this ride."

Once we accept this, then we can focus user assistance at the audience more appropriately.

Example
Let's say you were doing an embedded user assistance for a word processor, specifically the part of the application where you do Headings and Footers. I'd note in the embedded user assistance that headings can be automated by inserting a StyleRef field. I might add that this helps users find a topic by browsing the document header.

But what if someone doesn't understand style tags, should we put help about that in the embedded UA? What about principles of document design in general and what constitutes good heading hierarchies and should the StyleRef refer to Heading 1, Heading 2 or what?

Nope, nope, and nope. A snippet of help in a narrow sidebar in the middle of an off-main-page task is no time and place to educate the user about document design. It is a good place to ooch a fairly competent user to a higher level of efficiency or performance.

Put the training bit somewhere else.

Besides, what are the odds that your lowest common denominator is doing headings anyway?

Why I'm Not a Technical Writer--
And as Jerry Seinfeld would say, "Not that there'd be anything wrong with that." But I need to regroup and get my strategist hat back on here at my day job, and I feel the need to articulate and summarize what it is I do as a User Assistance Architect that is different from what I did as a technical writer.

Models
I seem to spend more time building models than producing documents. I do task analysis, just as a technical writer would do, but I seem to be less interested in "what a user needs to do" as much as "what would a user need to know?" And beyond that, I abstract one more level to "what kinds of information does a user need?"

I define patterns a lot. We have a department Wiki and I have a published pattern language I follow in posting patterns to our Wiki. By the way, I have an article coming out in the January/February issue of Interactions, the SIGCHI magazine. That issue will be a special topic issue edited by Fred Sampson focusing on User Assistance. My article is entitled "A pattern language approach to user assistance" (so much for coy titles). I hope folks get a chance to read it. I will be doing a presentation on this same topic at the WritersUA conference in Long Beach in March.

I wireframe a lot. I never did that as a technical writer, and frankly, I don't see a lot of technical communicators doing that. Wireframes let me model how the user assistance will behave. One reason we don't do a lot of that as technical communicators is that we are bound by the authoring tools. But that is tied into the model that Help is a separate application. As we get into more interactive models where user assistance is blended into the application, we need to wireframe how that works. Wireframing and use case modeling are two nifty disciplines I picked up while working as a UX designer at my previous job.

But I don't do a lot of use case modeling, and I'm not sure why not. Perhaps the pattern language approach fills the need that use cases did when I was designing UIs. But the other day, I did find myself looking at wireframes and asking about alternate and exception cases, so the discipline is still there and seems to influence me.

Content Management and Publishing Technologies
I spend a lot of time researching how we can author, store, retrieve, compile, and display information. Five years ago I would have been thinking about writing and publishing documents.

And somewhere in all that will eventually come architecture and tools.

Conclusion
Thanks for your patient ear. I'm stoked again.

My job is (1) to understand how our users apply information to their tasks, (2) how best to structure and deliver that information within the contexts of those tasks, and (3) how to author and manage that information so that it can be meet 1 and 2.

I gotta get to work!

Research, Periscopes, Cable TV, CSI, and Goldilocks--
In a tryptophan-induced semi coma this weekend, I experienced a convergence that tied my previous blog in with several seemingly disparate topics. The blog is from November 17, where I bemoan having to wade through so much meta discourse to get to actual content, e.g., "This chapter is about... This topic is about... This procedure is about..." Over the long holiday weekend, I was reading an article in the current issue of Technical Communication by some researchers in Washington state (BTW, kudos to the research leadership of Jan Spyridakis at the Un. of Washington) who studied the effects of the frequency of headings in online and print documents. The upshot of the research is that having too many headings is distracting in both print and online, but even more so for online documentation.

In my blog, I noted that the problem seemed more annoying to me when navigating a PDF through the bookmarks (which coincided with the block label headings) instead of scanning the printed manual. The research seems to validate that was not an isolated reaction. The extra navigation adds cognitive loading. But, the research also pointed out that too many headings had an aggravated negative effect in online documents even when the headings were not part of the navigation scheme, but occurred when readers scrolled through a multi-heading, monolithic block of text.

Periscopic Focus
My explanation is that reading online is like looking through a periscope; whereas reading print is like looking at the landscape from an open deck. In looking through a periscope, we seem to focus on detail more; therefore, we are more likely to interrupted by the headings (the speed-bump effect I describe in my earlier blog). The same thing happens to me when I read the program listings for my cable. The movie listing gives the cast first and then the blurb about the movie. Even though I have no interest in the cast, I find myself reading it. I think it is an effect of the periscopic focus from scrolling through the movie list.

Have you noticed on CSI that when the investigators enter the crime scene, they never turn the overhead light on? They use flashlights instead. My theory is that it helps them focus on detail and not be distracted by the broader landscape, so to speak. It forces periscopic focus.

Conclusions
The research reminded me and validated again that the online reader experience is less forgiving than the print experience. We need to get to the point as directly as possible.

As an avid Information Mapper, it also gave me pause to consider the potential downside to chunking at a too granular level, especially where limited screen real estate promotes aligning block labels with the body of the text (as opposed to the marginal outdenting more common in print presentation). In that presentation scheme, headings are more likely to interrupt the flow.

It also raises some interesting questions about structured writing in general where content is written independently of presentation media. Can content be authored with media-agnostic assumptions?

The good news is that the Goldilocks principle still prevails: Although too much is much too much online, just right seems to be just right in both print and online.

Metadiscourse--
[Warning: Taking any of the advice in today's blog could prevent you from winning awards in publication competitions.]

Metadiscourse is talking about the talking or writing about the writing. For example, the beginning of this sentence is metadiscourse; it has no content but tells you that what follows is an example. Metadiscourse can be a useful device to help listeners and readers know how to process what is about to come. Which, as an aside, has always made me doubt the effectiveness of putting them at the end of the discourse, as in this sentence for example.

Metadiscourse exists at the document level as well. For example, a table of contents is a form of metadiscourse.

I sometimes find myself having to wade through layers of metadiscourse to get to the value of a document. This seems most inconvenient when I am trying to navigate a PDF manual using the bookmarks. It seems like it takes me way too many clicks to get to where I find anything of value.
Example:
Ah, the chapter on Painting Widgets, just what I need. Let me click on Introduction:
"Introduction: This chapter is about how to paint widgets."
Hmmm. OK. Let me click on Overview.
"Overview: This chapter has the following topics:

• All About Widgets
• All About Paint
• Procedures"

I'll just click on Procedures:

"This section describes the following procedures:

• Selecting a color
• Preparing the widget
• Painting the widget"

Let's just go to Painting the Widget

"Follow this procedure to paint a widget"

AAAARRRRGGGGHHHHHHHH!!!!!!

We need to get readers to the good stuff quicker. How?

Don't make the TOC (or bookmarks in a PDF) overly detailed. Maybe just a listing of the chapters is all that is needed. An information-mapped document probably only needs chapter titles and map titles. Listing every block label in the bookmarks or TOC is probably excessive.

Stop writing chapters called "About this Guide" where we tell the reader why we italicize some words, do some in courier, some in bold, etc. I don't think the following scenario happens:

Hmmm here's a definition and the word browser is in italics. Let me go to Chapter One and see what's up with that. Oh, apparently browser is the term being defined. Glad I looked up the Conventions Used in this Guide piece.

And let's avoid Intros that restate the Topic title in sentence formats, or stem sentences that restate topic headings, etc. Let's rethink if every chapter needs a local TOC (or not call it Overview in the Bookmarks).

It's not that I don't know about nor value advanced organizers. But they're kind of like speed bumps; they're good too, but too many in short succession make me put the Wrangler in 4-wheel drive and take to the sidewalk.

End of Rant

The Heisenberg Uncertainty Principle--
Heisenberg says the more accurately we know where an electron is, the less accurately we can know what its velocity is. And vice versa. John Carroll talks about the Heisenberg Uncertainty Principle of Training: The more complete the training is, the less usable it is; the more usable it is, the less complete it is.

I believe the same goes for user assistance. The weight of being complete is not without its costs. For example, I recently read a user manual that explained the log in screen. By the way, this screen has two fields and one button. One field is labeled UserName and the other is labeled Password. The button is labeled Login.

It took a page with a screen shot to document how to log in. It turns out, after reading the manual, that I am supposed to put my UserName in the UserName field and my Password in the Password field. Then, according to the manual, I need to click on the button called Login.

There was some extra information: If I don't know my UserName and Password I should contact my System Administrator. And to get to the login page I need to type the IP address of the machine that is hosting this particular application in the URL address of my browser. Well, if I didn't know either of those things and went to the user assistance, I still don't know.

My question of the day is: If the UI is well designed and tells the user everything the user needs to know, do we need to document it at all?

What's the harm?
Why not document even the obvious? I can think of two reasons:

• It gets in the way. This user guide was 86 pages long. I can very quickly make it 85: Don't document the login screen. Let's assume that somewhere in that document is the one page the user needs. An 86-page document has 85 distractors (wrong or useless pages for that problem). An 85-page document has only 84 distractors. Not a big improvement, but hey, I was only on page two, who knows what I could do if I dug deeper.
• It fools us (the writers) into thinking we have documented the user's need. Maybe what this guide should have documented is how to read the IP address off of a machine. It was odd that it assumed a user would need help figuring out what to put in the Password field but would be adept at figuring out an IP address.

No Wonder Good Help Is Hard to Find--
I attended a delightful presentation at the local STC meeting last night called "Why I Didn't Hire You." Slides were clever, speaker was witty, and the content was a good encapsulation of conventional wisdom and sound advice for technical writers looking to get hired.

And that's what disturbed me.

The only part I liked was the part was about using the applicant's resume as an indication of the applicant's document design and information organizational skills. Right on!

The disturbing part was the behavioral advice concerning the interview: Hiring managers make their decisions based on criteria that have no correlation to what makes a writer successful.

Speaker's advice: "Dress professionally; who would you hire from the four men in this slide?" The right answer was the older white guy in the suit. One of the wrong answers was the younger African American man well-dressed but wearing a turtleneck shirt. Anyone want to venture a guess as to the speaker's demographic?

Similar question for the slide with four women. The winner was the attractive woman in a dress suit and perky tie. Loser was the slightly overweight woman wearing slacks and a man's tie.

My question was, "Who in these pictures look like the really good writers and editors I've worked with?" Losers in that category included the older white guy in the suit and the woman wearing the dress suit and perky tie.

OK, bad question. Try this one, "Who in these pictures look like the development team our writers would work with. Oops, same answer as before.

Other disturbing advice (disturbing because it really is practical and accurate): Don't ask questions about the work hours or the environment, like cubes versus offices. Yes, God forbid that hiring managers should act like they are recruiting talent, like they have a need to fill and they should try to understand what the candidates would like to know about where they will spend the majority of their conscious hours. The jobs are things the managers have and they will choose who is worthy to receive them.

What is wrong here? We have set up a system that evaluates candidates on criteria unrelated to success on the job, and we encourage candidates to present themselves disingenuously. What makes us think this is a formula for success?

I'd like to change the rules:
Candidates: Dress appropriately for the work environment and people you most likely will interface with. Be clean and neat, but be you.
Hiring Managers: Does the person look and act like someone who would fit in with the writers and SMEs he or she would work with.

Candidates: Ask questions that will help you make your job decision, don't make up stuff to sound good.
Hiring Mangers: Answer the candidate's questions and take them at face value. They have skin in the game too and have a right to interview you about how they will be treated by you.


Interviewing and hiring are fraught with subjectivity. Don't make it harder by introducing artificial criteria that at best can only tell you how well someone interviews.

It's bad enough that we practice all this deception when choosing life partners and people to make babies with. Must we muddy up the workplace as well?

IMHO :-)

Getting a Backbone--
I'm working right now on what will be essentially a getting started workbook. It will probably consists of an interactive document that queries the user for configuration-specific information, such as network topology, operating modes, etc., and it will provide specific user assistance for the user's configuration requirements. The latter might be delivered in discrete deployment guides (probably delivered as conventional PDFs) while the interactive document would be used primarily to determine which guide to point the user to.

So the core of the workbook is NOT procedural information, that comes later. The core must be conceptual information and guidance information so that the user can make informed decisions about how to configure the product. The flow of the topics will be determined by the deployment process, with the most important information being conceptual (background about the product) and guidance (considerations, criteria, and consequences of decisions that the user must make). After that, the user can be directed to detailed procedural information.

I've had a tendency in the past to view procedural information as the backbone of a user assistance document. The old P-K analysis approach: Define what procedures the user must do, then analyze what other kinds of knowledge you must impart for them to understand the procedures. I'm certainly not throwing that baby away with the bath, but I'm coming to see less and less importance in defining the sequence of steps and seeing more importance in imparting expertise to support the user's application-level goals.

In short, if it's that hard to figure out how to work the application, shoot the UI developer. The challenge for the UA should be helping the user figure out how to apply the application to the user's goals.

Conclusion
Make the higher order information (what I've been calling conceptual and guidance) the backbone of the user assistance, and let procedural information branch off and out from that core.

Dumb or Brilliant?---
This one has me pondering. We have a user interface where the user can enter IP addresses. If the user wishes to enter multiple IP addresses, the instruction is to separate them with a comma. The UI displays the addresses as the user has entered them. Very similar to how you see multiple email address in the To field of an email. No problem.

On a new interface, when the user types a comma, the display treats it the way it would a carriage return, putting the new IP address on the next line. Huh! Easier to read and see what addresses have been added; different user experience. It raises two questions I find interesting:

• Should the UI display what the user typed or what the user decided? Using the comma to tell the computer, "This is a new IP address" is easy for the input phase, but should it preclude the computer from acknowledging that input in a way that is easier to process visually for the user.
• To what degree should innovation be constrained by convention (or consistency)?

No answers today. I'm enjoying the questions too much :-)

An Old Standard Revisited: Flow-Charting--
My earliest exposure to flow charts was as trouble-shooting aids. As I watched people use them, they did not seem very effective; users often got lost and the user experience rarely seemed to end with the trouble getting shot.

This last year, however, I have found myself going to flowcharting as an analysis tool, one to help me understand complex navigations or tasks where logical branching played an important part. For example, in one application, clicking the Done button could take different users to different locations depending on what path they had taken or decisions they had made.

More recently, I have been using flowcharts to understand how a complex task is done (configuring a network security appliance), especially to understand the different contingencies and how the user path is affected.

I use Visio's standard template for flowcharting and sit in design sessions with my laptop projected. The team of SMEs, information architect, technical writer, and I have been mapping the flow and logical branches of a very complicated process in order to create an interactive guide that could query the user about configuration decisions and deliver the appropriate information.

I have also created four new icons in my template, one for each of the main kinds of information:

• Conceptual
• Procedural
• Guidance
• Reference

I use these icons to annotate the flow chart as to what kind of information a user would need at the various steps and phases in the flow.

An interesting pattern is emerging. Where there are decision/branching diamonds, there is often a need for conceptual and guidance information. In other words, the user needs some background about the domain and also needs expert insight into the decision to be made. For example, if a branch requires that the user decide between "transparent" or "routing" mode, the user assistance must make sure the user understands these terms (conceptual information) and also provide guidelines for when to choose one over the other, implications for that choice, etc (guidance information).

Procedural information icons tend to show up at action blocks in the flow.

Nothing shocking here, but it's nice to change lenses every now and again and find that the same features you thought were important still show up in the landscape.

So don't discount the value of flow-charting as a collaborative task-analysis tool, and be aware that it can then be easily turned into a contextual information requirements tool.

Applications as Tools--
In one of my earliest blogs I pointed out that the term "user" implied something "used." Part of understanding how to craft effective user assistance requires an understanding of different ways things are used.

I see applications as falling into one of (or drifting among) three levels of toolness:

• Extension tool
• Cognitive tool
• Electronic Performance Support System (hat-tip to Gloria Geary)

Extension tools are a lot like simple mechanical tools: They extend a natural physical capacity. Think of a crescent wrench. It grabs a nut much the way our fingers would, just stronger and tighter. The wrench's handle amplifies the natural torque our arm provides. Similar thinking for a hammer: Its head is like a small hard fist and its handle amplifies the power of our arm.

A simple word processor (or one where just the basic functions of text entry and editing are used) is an extension tool. We can type, erase, and print pretty much the way we would write (or talk) manually--just faster and more legibly.

Cognitive tools help us think. What if instead of just sitting down at the word processor and typing a memo, I started in the outline format and organized my thoughts. Then as I wrote, I used the outline to evaluate the flow of my argument and dragged elements around until I felt the document flowed better? There is more going on here than using the word processor to make the task easier from the mechanical perspective. The tool is supporting higher order processes of rhetoric, composition, and critical thinking.

An Electronic Performance Support System (EPSS) brings data and domain expertise (guidance) to the user. Today's word processor, with spell check, templates, wizards, and collaboration tools, is very close to acting like an EPSS if not actually doing so.

Implications for User Assistance Architecture
As user assistance matures in a product, it moves the product up the tool hierarchy. When user assistance as a separate help file largely goes away and is replaced by more proactive strategies within the UI, it has elevated the product to an EPSS.

THAT is the value sweet spot.

What's Your Underlying World View?--
Philisophically, technical writers fall into two epistemological camps (hey! it's my blog; I can use words like that if I want): Positivism and Constructivism.

Positivists
Positivists view reality as singular and rigid: An apprehendable reality is assumed to exist, driven by immutable natural laws and mechanisms. Knowledge of the way things are is conventionally summarized in the form of time- and context-free generalizations. (Guba and Lincoln 1994, p. 109)

Positivist technical communicators tend to define a product by a finite set of features and functions. An accurate and complete cataloging and description of the features and functions will render an accurate and complete description of the product.

Positivists view the relationship between the knower and the thing known as dualistic: There is a distinct separation between the knower and the known. They view reality as being objective: Facts are true or false. They view the role of the technical communicator as being an unbiased describer of a product's functionality.

Constructivists
Constructivists view reality as pluralistic: Reality is expressible in a variety of symbol and language systems. They also see it as plastic: Reality is stretched and shaped to fit purposeful acts of intentional human agents. (Schwandt 1994, p. 125)

Constructivist technical communicators define a product by how people interact with it. No description can ever be complete or totally accurate since the permutations of possible user contexts are too complex.

Constructivists view the relationship between the knower and the thing known as transactional: Meanings are created, negotiated, sustained, and modified within a specific context of human action. The means or process by which the inquirer arrives at this kind of interpretation of human action (as well as the ends or aim of the process) is called Verstehen (understanding). (Schwandt 1994, p. 120).

They also see it as subjective: Facts are deemed viable or not viable within a community of practice.

Constructivist technical communicators interpret product functionality in light of both the user contexts and the developers intentions.

...

Whereas we take many of our disciplines and values in technical communication from our positivist past, the future of user assistance lies in a constructivist vision .
___

Guba, E. G., and Y. S. Lincoln. 1994. Competing paradigms
in qualitative research. In Handbook of qualitative
research, ed. N. K. Denzin and Y. S. Lincoln. Thousand
Oaks, CA: Sage Publications.


Schwandt, T. A. 1994. Constructivist, interpretivist
approaches to human inquiry. In Handbook of qualitative
research, ed. N. K. Denzin and Y. S. Lincoln. Thousand
Oaks, CA: Sage Publications.