The Information Model

Continuing our discussion of using Excel rather than Word or Project to manage an information project.

A simple spreadsheet that I get a lot of use out of is one I call the Information Model. I use it first to plan my information content, then to estimate the development time for each topic (or group of topics) track who is responsible for each, the due date, and its status. It is a simple, flat table in Excel that has columns labeled Topics, Info Developer, Status, Estimate, Due Date, and Comments (for starters).

If you are revising an existing document, the topics in the spreadsheet can be taken directly from the existing document. If the application you are documenting has a UI already, you can list the UI pages themselves as the topics. If you are using use cases, you can add a column to help organize your topics by the use cases or scenario names that describe the user tasks you intend to support.

You can now use the same spreadsheet to assign different topics to different information developers.

You can also use the spreadsheet to size the project. For example, in one project the general scope of a screen could be described by the number of tabs it had. So I created a column called tabs and we inventoried how many tabs were on each screen. We then estimated that each tab would take a half-day to document, so we wrote a simple formula in Excel to estimate the days each topic would take by multiplying the number of tabs by .5. We then summed that column to see the total project estimate.

• Tip: Put the estimation variable (in this case we started with .5) in its own cell and point to it in the estimation formulas. For example, if the estimation variable was in cell H3, and the number of tabs for a particular topic was in B5, the estimation formula for that topic would be "=$H$3*B5" Note: The $ makes that an absolute address, so if you copy that formula for all the topics, B5 will automatically change to the appropriate cell that contains that topic's number of tabs (e.g., C5, D5, E5, etc.), but the estimation variable will always come from H3. This way you can play some easy "what if" scenarios by changing the estimation variable in H3 and instantly seeing the impact it has on the project time.

Once the topics have been sized and assigned to information developers, you can ask each info developer to schedule their assigned topics. For example, if an info developer thinks she can devote an effective 3 days a week to the project, then she could group topics into weekly chunks by assigning the same weekly due date to 3 days' worth of topics. Or if a topic would take 6 days, she could make sure she allocated two weeks to get it done.

• Tip: Have info developers make all topics due on Fridays. That way the project manager or department manager can filter by a given date to see everything due that week.

And that last tip brings up a really useful feature of Excel, the ability to apply filters. Once you have your table built, do the following:

1. Highlight the heading row for the data columns.
2. Click Data > Filter > Autofilter on the menu.

You now get drop lists at the top of each column that let you filter and sort the table by the data in that column. This lets you do things like see only the topics that Mike is working on, or only the topics that are due this Friday. You can apply multiple filters, e.g., see Mike's topics that are due this Friday or see Mike's topics where status is blank.

Of course this approach needs to be modified for what make sense in your world, e.g., I like weekly scheduling units, you might prefer monthly. But the point is, if you put your plan in a spreadsheet instead of a document, you get a more powerful database and calculator tool to help you plan and track the project.

Plan vs. Planning

[Duh! after almost two years on Blogger I figured out that there is a "title" block that is not turned on by default. I looked for it when I started transferring my rss reads from NewsGator to Google Reader. All of my blogs said "No title" and everybody else's had titles. It's the cyber equivalent to spinach in the teeth-it leaves you wondering why no one tells you :-0 ]

Documentation Plans: One out of Three Rs

We have a couple of overlapping projects going on at work these days. One is to establish ourselves at Level 3 on the Information Process Maturity Model. Another is to be more compliant with IBM's Information Development Standards. The upshot of this is that I am reflecting on the planning process a lot these days, since both of these efforts deal with planning.

My second career (after being an electronics technician--so long ago I know how vacuum tube circuits work) was in Manufacturing Management, so I have a natural fondness for project planning and tracking which I carried forth into a later career of documentation management. In my current career as Information Architect I find my need for project planning and tracking tools are still welded to my genetic structure. But I have noticed my tool of choice has changed over the years and that my reverence for "the plan" has diminished a bit. But not my respect for "planning," which is what this blog is about.

In short, a lot of mature departments and those striving to be mature place a lot of importance on a written documentation plan, often produced in MS Word and sometimes accompanied by a formal project plan done in MS Project. If I had a nickel for every such plan I've done--well, I'd have about $1.35, which rhetorically doesn't sound too impressive after having done the math, but you get the idea; I've done it a lot.

I think documentation plans have some serious flaws:

• We do them when we are the stupidest about what the project is about and whom it is for.
• Although we write them (one R), I'm not sure anyone reads them (second R).
• Lastly, they lack detail and the underlying engine to do the estimation math (the third R 'rithmatic).

I think project plans done in a project planning tool also have some serious limitations:

• They treat the project as if it is progressive (it keeps moving forward in discrete chunks) and linear (it moves in a straight line). In reality a project is expansive (we learn more about the product, the users, and our production tool sets the further into it we get into the project) and recursive (this expanded knowledge we get by the time we're on chapter three makes us need to rewrite chapter one).
• The critical piece of information we are all after, task duration, is an input and not the result of anything the tool helps us with.
• Whereas just about everybody has Word, Project is not as ubiquitous and distributing the project plan is not as easy as distributing a Word document.

My Tool of Choice

I find I'm getting much better results by using Excel as my planning and tracking tool.

• I spend more time thinking and noodling and less time on writing a document. The subtle difference is that I have shifted my emphasis from "making a plan" (where the plan is an artifact to be distributed and checked off) to "planning."
• Excel is great for making and manipulating lists. Once I have identified topics, assigned writers, categorized topics, set dates, whatever, I can filter and sort by any of those classifications.
• Once the list of topics is created in Excel, I can use its calculation capabilities to help me estimate the project.
• Everybody has Excel and the plan, schedule, and tracking file for a project (a single workbook with multiple worksheets) can be placed on a shared drive and be viewed and updated by anyone on the project.

The problem is that Excel is not usually considered a technical communicator's tool and so we do not get exposed to it in school or at the conferences. I'd like to see that change, since it is uniquely capable (by "it" I really mean a spreadsheet tool) of letting a project plan mature from broad, static statements to detailed inventories of information topics to be developed and then let you calculate estimates for those topics and create realistic schedules that can be monitored at a weekly granularity.

For the next few blogs, I will discuss in more detail how a spreadsheet can be used to plan and monitor information development projects. Even if you do not throw away your conventional documents about documents approach to planning, maybe you will find it worthwhile to stick a couple of more Rs into the process.

Moving on up...

I am officially moving from the world of paying for services I can get for free. At the end of this month I will be shutting down my Mindspring account. This means I lose my old e-mail address and my web page. New email is michaelhughesua@gmail.com I will be using this blog space to replace my old web page.

I will also be dealing with the gas crisis by working from home two days a week. This has meant putting in a high speed connection that lets me get into my Lotus Notes and the IBM Intranet. What a pain that was--but it's all done. Things I didn't know: Fiber optic DSL does not use a modem, and my company's VPN apparently needs the IP address a modem attaches. So one week of doodling with fiber optic down the drain. So I now have cable Internet access which comes with a modem. Another lesson learned: If the cable installer uses your desktop computer to test the modem (while you're at work) the modem will not work on your laptop that night unless you power down the modem and start it up again, after you connect it to the laptop. As a technical communicator I was ticked that such a simple requirement took me two hours to learn (and learn eventually from a tech support call). Add to this that the first time they came to install the modem they didn't come prepared to install the cable (duh!) and when I called tech support and waited on hold to get a human, they disconnected me when they tried to transfer me the the right tech.

Enough whining, but I do wonder how we make money off of technology when the usability barriers to entry are so high. The latter problem was not a technology issue, it was a UX one. The modem was beautifully designed--IT DID EVERYTHING! The breakdown was that the installer tested it on one computer, disconnected it from that computer and left it powered up, looking "ready to plug and play." I did the natural thing and plugged it into my laptop. The user experience failed because the installer should have (1) Turned power off to the modem and (2) left instructions.

Lesson learned, user experience is a process that crosses all kinds of disciplines. The doc is just one element in the system and the critical channels often have nothing to do with the technology.

STC Summit

The original title was supposed to be "I Rolled Holly Harkness" after I gave Holly my dinner roll at the Honors Banquet, but that seems too indecorous now that I am in a more sober mood (well, actually, now that I am sober). It's not so much the improper innuendo, mind you; it's the use of a noun as a verb that I find most problematic.

I would be just lying through my teeth not to admit what a great time I had at the Honors Banquet being inducted as a Fellow in the society. I can only say that it is a thrill mainly because I hold my fellow STC members in such high regard and consider our profession to be truly important. Barrie Byron was kind enough to send me a picture of my special moment.

The conference was great, Philadelphia was a delight, and I am exhausted after 2 days of board meeting, a leadership day, and three days of conference. Atlanta folks, be sure to attend our next chapter meeting when conference attendees will report on the conference.

I am also proud of how visible the Atlanta chapter was at this year's conference--Robert Armstrong was Track Manager and Coordinator for the Producing and Publishing Information Track, our chapter won a Community of Excellence award, and Al Hood has taken on a significant volunteer role with the Leadership Community Resource. Holly, Robert, and Al attended Leadership Day on Sunday along with our president, Howard Speck, and our 2nd VP, Jen Collier. Margaret Cekis, Holly Harkness, Al Hood, and I were presenters--I'm sure I missed someone in that list, sorry.

AND, we are the host chapter next year and will get cranking up on that real soon.

So I am back home, both exhausted and rejuvenated at the same time. We live in an exciting time where our profession can have a real impact on what's happening in the world and in the marketplace, and where we can have a real impact on our profession. Go STC!

Patching up the crack...

Ok, you have to be pretty old to recognize the context of that reference. It's from the theme song to Disney's David Crockett series: "He patched up the crack in the liberty bell." I'm all packed and getting ready to go to the airport for Philadelphia and the STC Summit. First I have a two-day board of directors meeting, a one-day leadership day orientation and then the Summit. I will be speaking on Tuesday from 3:00 to 4:00 on how to use Excel to compare averages for statistical significance. It can be useful for comparing quantifiable data (user ratings, time to do task, etc.) between two products, two versions of a product, or different groups of users. It's a little dry, but I make up for it by talking very loudly.

Speaking of context, I stirred the pot a bit in my current column in UXmatters. Partly due to its reference to culture and partly because I advocate against the need for documentation that explains the obvious. Lots of comments. Please look at the column and weigh in if you want. David Farkas came to my defense-I'm cutting it out and putting it in my scrap book!

I've redesigned my blog site to contain links to my publications. This is in anticipation for dropping my web page. I'm trying to follow Sarah O'Keefe's 80/zero rule. Get 80% of the functionality you need for zero cost. So I'm going with all free hosting and services. It's kind of like being a cyber dharma bum.

If you are a reader of this blog and you are going to the STC Summit in Philly, please look me up and say hi.

Just a brief, newsy blog to keep my I'net pipes running.

Two great blogs to check out:
http://dontcallmetina.wordpress.com/2008/05/20/future-doc/ Holly Harkness's blog Future Doc is a rich summary of a speaker she heard. Very provocative.

http://www.mirandabennett.com/onwriting/?p=20 See Miranda Bennett's blog on Translation Phase 2. Need a teaser? Phase 1: Collect underpants.

My column in UXmatters is my take on Jean-Luc Dumont's road sign presentation he did at Currents and how I think it applies to writing user assistance. http://www.uxmatters.com/MT/archives/000292.php

Lastly, now that I am teaching a summer course in research in technical communication (shamelessly requiring my book as the text), I am reminded that Education is the only business I know that gives all the good parking spots to the employees and makes the customers walk.

There, that should have my I'net pipes running clear.

Step Results: Clutter vs. Assurance

Sometimes a result statement in a step just adds clutter and annoys the readers (if not out and out insults their intelligence).

Example

1. Click on Print Properties. The system displays the Print Properties dialog box.

Always useful in case the user wonders what this box is that just popped up that says Print Properties.

Most user assistance writers use result statements sparingly, but there are situations in which they are very valuable:

• If the user might be unsure what action the system will take and that uncertainty could make her reluctant or anxious to take a step
• If the system does something significant in the background that the user will not be able to see

Examples

I had this one today. The user interface had a link that said "Click here to update to version 1.5839" displayed in blue font and underlined in normal link convention. I didn't know if it was a true link or if it was a link being used in lieu of a command button. Was I going to go to a screen that told me what 1.5839 did or would I just launch the update? It turned out that I got a confirmation box and then the update. In that case, the Help should include result statements:

1. Click on the link Click here to update to version version number. The system displays a confirmation screen.
2. To confirm that you want to install the update, click OK. The system installs the update.

Why? Ambiguous UI control.

Result statements can also be useful when the UI is weak on confirmation messages:

1. Fill in the form.
2. Click OK. The system updates the record and clears the current form.

This deals with the angst of suddenly having your data go away and wondering did it go anywhere useful. I think a lot of my data goes to a house in Indiana that has the lightbulb that the switch in my hallway turns on and off. I think some of my singleton socks are there too.

A techwriter dies and goes to heaven...

and she finds herself at the pearly gates before St. Peter. He looks over her record and decides she is worthy to enter heaven.

"We've upgraded our services recently," he tells her, "so that you now have access to a more personalized heaven experience. Since you are a technical writer, I'll show you several versions of heaven behind some of those doors over there that have been expressly designed to enhance the technical communicator's heaven experience."

"Wow," the techwriter replies with excitement.

"The only problem," St. Peter tells her, "is I just got a text message from the boss and I have to handle it. I'll be back in a few minutes and then I'll give you a tour of your heavenly options."

With that, St. Peter steps away, leaving the techwriter standing in front of three doors. Her curiosity gets the better of her and she opens the first door. There she sees a work station with a bazillion-pixel, high def screen, screaming CPU with graphical coprocessors, loaded with all of the latest authoring tools and a high-speed connection to the UWW (Universal Wide Web). She tries a Google search and instead of getting two-million hits she gets just five, and they are the perfect five.

"This is way cool," she thinks to herself.

She decides to see what's behind the second door. There she finds a cosmic Starbucks. Instead of walls and windows, the table are open to the entire universe and you can almost touch the planets and the stars. Instead of paper cups, the coffee is served in deep blue china mugs. She sees a person putting sugar into her latte (in heaven sugar has no calories) when a tiny paper clip walks across the table and knocks on the mug with a sound of tiny knuckles on glass--tink tink tink!

The paper clip speaks, "I see you're trying to sweeten your coffee, can I ..."

At that point the person fixing her coffee picks up the paper clip, takes a rubber band, and shoots the paper clip out into the vast emptiness of space.

"How cool is that," says the techwriter.

St. Peter hasn't returned yet, so she looks behind the third door. There she sees a technical communicator in a meeting room with developers and she is discussing a user interface being projected onto a screen at the front of the room.

"For one thing," she says to the developers, "you've used 'data base' as two words in the title but as one word in the actual screen. Our style guide says database should be one word."

There is a general round of approvals and one of the developers says, "That's why we need technical communicators on the team."

The technical communicator at the front of the room continues, "And if the user doesn't put the right date format in the date field, you pop up a rather cryptic error message. I think you should just put in some client-side scripting that accepts the user's format and converts it to the format the database requires."

Once again, a general round of approvals and someones says, "Of course, it takes a technical communicator to see it from the user's side. We were too focused on the back-end requirements."

And then the technical communicator says, "I have a report from a usability test we did with real users doing authentic tasks with this UI. I can make the results available to you."

Once again, enthusiasm abounds around the table and someone says, "This is why we need technical communicators on the dev team, they keep us focused on the user, and they have real data to back it up."

At this point, the techwriter hears St. Peter returning and she hurries back to the gate.

"Well," St. Peter says, "let's show you some options for your personalized heaven experience."

"Oh, St. Peter," she says, "I can save you some time. I found my technical communicator heaven; it's behind the third door."

St. Peter looks disappointed. "Oh no," he says, "there's been a misunderstanding. That's not technical communicator heaven; that's the door to developer's hell.

The two most common comma mistakes I see good writers make

As hard as it will be for many of my colleagues to believe, I actually know a couple of grammar rules and even advocate that people follow them.

I just finished a couple of weeks of peer editing and saw good writers making similar mistakes, the same mistakes I see good writers make a lot. The problem, I think, is that our brains know the rules but our fingers ignore them under the pressure of deadlines or when the muse is inspiring us with good content. But for what it is worth, here are the two comma errors I see most often (so if you are guilty of either or both of them, you are in good company).

Punctuating compound predicates as if they were compound sentences

A compound sentence has two complete clauses joined by a conjunction. A comma comes before the conjunction. Example: John wrote the user guide, and Mary edited the installation guide. Two subjects each with their own verb.

A compound predicate has only one subject but two verbs. No comma is used. Example: John wrote the user guide and edited the installation guide. If you absolutely long for a comma in the second example, you merely have to add a subject as in: John wrote the user guide, and he edited the installation guide.

Good writers usually make this mistake when the predicate elements are long, as in: John wrote the user guide that went with the latest version of the TurboPro Archiver, and edited the installation guide that went with the X-Level Wiki Mapper for Linux.

Long, but still a compound predicate and no comma.

Separating a two-item list with a comma

A two-item list does not take a comma. You would never write: You can choose option A, or option B. But as in the first error, good writers confuse themselves when choices get wordy: You can assign users to a category based on the permissions you have granted them in Section 10.4, or based on the profiles you establish in Section 14.6.

Long, but still a two-item list and no comma.

What is getting in the way in both examples is long sentences and the mythical comma rule of "use a comma when the reader needs to take a breath."

No such rule. No NEED for such a rule. None of us has written a technical document so compelling that the reader forgot to breathe. In my own case it's as if I breathe without even thinking about it. My lungs suddenly get hungry for air and wooosh; it just happens. I don't think I've ever heard of a situation where a reader was found blue and unconscious with those around him saying, "Oh my god! If only the technical writer had told him to breathe."

At any rate, be mindful that our fingers and this mythical rule are out to put spurious commas into the otherwise well-punctuated prose of even the most seasoned veterans among us. Keep a watchful eye out.

I won :-)

Get dressed, we're going to a party

On April 22 the Atlanta STC chapter is having its annual awards banquet. Holly Harkness has gone all out to make it a stupendous evening (by that I mean the food will be good, we're going to Maggiano's).

So here's my question: If you are not getting an award, why go to this event? Here are my thoughts:

• If you only go to church once a year, it's usually on Easter Sunday. It lets you remind yourself what religion you belong to, and you get to see everybody all looking nice. If you haven't been going to STC meetings, this is a good one to go to for the same reasons.
• An awards banquet is about professional excellence. Hey, that's why you joined a professional society in the first place. This could be the most important meeting you attend. (And if you're not a member, this is a great way to get introduced.)
• The winning entries are on display. This is the best way to survey what the current standards of "best practices" are.
• You'll be networking with the thought and practice leaders in the area.

Remember when being a tech writer was fun? Join me at the awards banquet and let's have fun again.

Reply versus Reply All

My e-mail inbox is cluttered by something other than SPAM. I am on a number of committees and list servers where I must wade through large amounts of chatter that does not add value, but takes up my time and effort to get rid of. Last week I accidentally deleted an important meeting invitation because I inadvertently deleted it along with this category of junk mail.

Here's what I'm talking about. I got an e-mail reminding me that there is a board meeting this Friday that goes out to all of the board members. That's good. The e-mail asks attendees to verify if they are going to have lunch so that the organizer knows how much food to order. Now starts the litany of emails from individuals saying "I'll have lunch." I get these because the responders click "Reply All" instead of "Reply." (This is just one example of a phenomenon I experience several times a week if not daily.)

STOP IT!

"Reply All" sends your answer to everyone on the original email. Use "Reply All" when your answer applies to everyone, or you want to open up your response to the public scrutiny of the group you are participating in. Who am I to give feedback on who should be eating lunch?

"Reply" sends your answer just to the person who sent you the email. In the example above, only the sender needs to know if you will show up hungry.

And list servers have a sneakier version of the same problem. "Reply" sends the answer to the list server list (EVERYBODY), not the person who wrote the post. That is because the e-mail did not really come to you from the individual; it came from the list server.

I'm sorry for the cranky post.

New Column

I have a new column out in UXmatters today called Placing Value on User Assistance. It's a topic I have blogged on before, but the column has a nice shiny picture as my colleague Mark Wallis would say. Speaking of Mark and pictures, right after WritersUA, Mark let me be his gear monkey while he took nature shots around and up Mt. Hood outside of Portland. Awesome! We went from mossy rain forests to 25 feet of snow in less than an hour.

WritersUA was great. The presentations were their usual high caliber, the vendors just chock full of new features, and the networking as valuable and enjoyable as ever.

Great Currents Conference

I went to the Atlanta STC regional conference, Currents, this Saturday. As always, it was a great professional motivator and a chance to chat with some of our leading technical communicators. And Jean-Luc's final slide was right, I will never be able to look at a road sign the same way ever again. Yesterday on my way to the airport, I saw one of Jean-Luc's favorites:

State Law
STOP
Yield to pedestrian in crosswalk

Jean-Luc's point is that it is strange that we need to be told to do this, as if we would have hit them otherwise, and that we must be told it's the law (as opposed to a guideline, I guess.) Jean-Luc forgets that we are the culture that created the video game Death Race 2000 where you get points for hitting pedestrians.

The reason I was going to the airport is that I am in Portland, Oregon, this week for the WritersUA conference. First Currents and now WritersUA! I'll try to post on the conference this week.

One more thing, on the Portland light rail, nobody checks to see if you bought a ticket. It's the honor system. Kind of a nice contrast to "No running over pedestrians or else we'll give you a ticket."

Instructional Text on the UI

Embedded assistance makes us reevaluate some tried and true principles of information design because our instructions occur within an action-packed medium--an application's user interface. If you think you have trouble holding a student's attention in the classroom, try teaching in a video-arcade. In many ways, embedded assistance has the same challenge.

Having said that, I'm going to shoot you over to a column I wrote a year ago for UXmatters called Instructional Text in the User Interface: Some Counterintuitive Implications of User Behaviors .

News

• Check out Martha Stevens new blog on user assistance. Martha's voice and insights will be a good addition to the blogosphere.
• Currents (Atlanta STC regional conference) starts in a few days. Shout out to my buddy, Miranda Bennett, who will be doing an interesting presentation on collaborative walkthroughs.
• And with the start of daylight savings time, I'm back on my routine of going fishing every Wednesday afternoon after work. Actually, I sit in my kayak on Stone Mountain lake, drink two beers, and smoke a cigar while pretending to fish. I have come to the very serious realization that life balance is important; do you have something you make time for every week that is just for you? (Tip: Scheduling something for mid-week is a great way to break up the work week.)
• Voting for STC officers starts next week. If you are an STC member, vote early; if you're voting for me, vote often.

MOO POPs

I want to discuss MOO POPs early in this series of blogs on embedded assistance (EA) because the concept drives straight to the heart of EA: When and where do we need it?

MOO POP stands for "Moment of Opportunity" and "Point of Pain." A moment of opportunity refers to a state in the user interface when we can intervene and move the user to increase his or her adoption of the product. I wrote an article for the Cutter IT Journal last year about progressive user adoption that talks about the ability of embedded assistance to increase user adoption of advanced features based on detecting user readiness for that advanced feature. For example, a useful feature in Microsoft Word is its ability to automate header content using heading tags in the document, such as making the current Heading 2 the header entry. When would you point that out to the user? If someone is in the act of defining a header, that could be the appropriate moment of opportunity. Imagine a link on the header dialog box that said "Tell me how to automate my headers" and which launched a popup that explained how to do that.

A point of pain is where we anticipate that the user might run into trouble. For example, if we provide a field for entering the name of a firewall rule the user is creating, and the developer points out that the database cannot accept spaces in the name, we can reasonably anticipate that some users will screw up. A simple statement next to the field that says merely "No spaces" will save innumerable instances of error messages popping up. In general, the following situations are good candidates to be points of pain:

• When choices or actions are grayed out (Hey! why can't I do this?)
• When we ask users to make decisions (Did you want DES, 3DES, or AES encryption?--say what!)
• When business or validation rules will lead to likely error conditions

So one of the first lessons in doing embedded assistance is that you do not have to be consistent, and by that I mean you don't have to treat all fields equally. The field that asks the user to type her first name does not need embedded assistance; the field that asks her to create a new password probably does (as in what are the rules for a valid password).

The guiding principle should be "Is there a moment of opportunity or point of pain that justifies taking up room on the user interface?"

In my next blog, I will talk about how to maximize effectiveness and minimize the intrusiveness of the EA entries on the user interface.

Embedded Assistance

I'm working these days on some very exciting projects involving embedded assistance. Embedded assistance (EA) is user assistance that is incorporated directly into the user interface, specifically, assistance that does not require the user to go into a Help file or document. Although most people think of embedded Help panes that exist along the right or left side of the application screen when you say embedded assistance, that is just one aspect of EA--and quite frankly, one of the less important elements. Embedded assistance incorporates any text or communication within the user interface that informs or instructs the user:

• Field labels
• Inline instructional text
• Error or information messages
• Button labels
• On-screen examples
• Hover text
• Tool tips

And beyond this obvious list of element where words are involved, I also include other design considerations such as grouping and sequencing of fields on the UI.

I'd like to give a shout-out to Fred Sampson, a colleague of mine within IBM, for the leadership he has shown in taking me down this path. In the next series of blogs, I will be relating research and guidelines Fred has helped assemble along with tips and how to's from my own experiences helping my division move in this direction.

Why embedded assistance?

Today's blog focuses on why user assistance writers should shift their focus from traditional Help and concentrate more on embedded assistance.

1. Users don't go to Help.
2. Embedded assistance keeps users in their task flow.
3. OK, some users eventually go to Help, but then it isn't helpful.

Users don't go to Help

In most corporate cultures there is somewhat of a dichotomy between working and learning. By that I mean we think of the two as being different activities. We say things like "I won't be at work next week because I'm going to the WritersUA conference." Or when an inhouse training session comes to an end, someone invariably says, "Time to get back to work."

Users see going into Help as being an interruption to work. I used to complain about users who were "too lazy to read the manual" until I started doing usability testing. I then realized that the users were working very hard to get the task done, and they were not going to Help for that very reason, they were focused on the task and that is where they felt they should stay.

Staying in the task flow

The best place to put user assistance is in the UI where and when the need occurs. I like to talk about MOO POPs--no, not milk-based Popsicles, moments of opportunity and points of pain. Understanding where the MOO POPs are in your application is a critical aspect of designing good EA. I will blog on that later.

Why Help is anything but

When I watch users doing a task and then watch when they eventually go into Help, more times than not the Help is not helpful. It's not the writer's fault. See my UXmatters column Stepped Procedures: The Sacred Cow Blocking the Road for an explanation of why there is often a mismatch between the user's question and Help's answers.

Upcoming blogs

Tune in for the next few blogs as I go deeper into the following:

• MOO POPs
• Progressive disclosure (an essential technique for EA)
• How to sell the developers on letting us into the UI

February 29th: Bonus Day!

Every four years something remarkable happens; we are given an extra day. Today is that day; do something with it. Here are some options.

• You probably have the latest Intercom or Technical Communication sitting on your desk. Find a good article in each and read it.
• Your inbox has 476 emails in it. Clean them out.
• Download trial software and play with it.
• Organize the rest of your year.
• Go around the office being extra nice or cheery.

You get the idea. Today is a free day, a time-out from the 365 day grind. Make it special and in doing so make yourself special.

Happy bonus day!

Currents Is Almost Here--
In times of tight budgets (and why are we ALWAYS in times of tight budgets) the Atlanta regional conference Currents is a great professional development bargain for those in the neighborhood. So put March 14th (workshop day) and 15th (sessions day) on your calendar.

The quality of the presentations is world class:

• One of the speakers, Dr. David Yates from Auburn, has an article in the just published February issue of Technical Communication.
• At least four university programs are represented: Mercer, Auburn, Georgia State, and my alma mater SPSU (also the venue of this year's event)
• Speakers from major corporations will share their insights: IBM, Mirant, ComponetOne
• I can see that at least two of the presentations (mine and Carol Barnum's) are part of the 55th conference in Philadelphia.
• STC leadership will be there: Mark Clifford, STC 1st VP (upcoming president in June)-- and local boy 2ndVP candidate will be there kissing babies :-)
• International keynoter: Jean-luc Dumont--just saying his name is worth the price of admission

And the networking is always great. So get your head out of the read-me you're working on, or that configuration guide, and rub shoulders with fellow professionals and talk about your craft. Celebrate your professionalism!

For full details go to http://www.stcatlanta.org/currents.htm