What's in your backpack?

My buddy Miranda Bennett apparently shares my life philosophy of "Anything worth doing is worth overdoing." She wanted to get more exercise so she took up backpacking on the Appalachian Trail. You go, girl.

Someone in the group she joined was helping her sort through her backpack and gave her the following observation, "Your gear is your fear." Apparently, it's an esoteric principle known to backpackers and essentially means that whatever you're afraid of will be reflected in what you overpack. So if you're afraid of getting lost, you might have four maps, two compasses, and a GPS. Afraid of being wet? Two ponchos, galoshes, and five changes of clothing.

Every now and then I get that old "fight or flight" reflex at work. I doubt if I'm unique in that. But I'm a technical writer, and no one is chasing me with a hatchet and there are no lions hungrily walking our halls. So I have to ask, "What am I afraid of?"

If that happens to you, look at your gear. Not now, it won't work. Wait until you have that adrenaline rush that says get the hell out or stand your ground swinging. When that happens, take a serious look at your gear, that is, the artifacts, books, tools, and other stuff you have surrounded yourself with. You could also check out the emotional baggage you like to haul around as well.

Keep what you need, put some of it away, and then walk your trail.

Thanks, Miranda!

The snarky technical writer

Who knew that Lewis Carroll and Henry Holiday understood the world of technical writing?


I don't know what more accurately describes our world, the flying pigs or the tormentors. Take the link below for a fun read.

Fit the Fifth

For a few moments I was special

Those not following national news, Georgia had the last contested seat in the Senate up for a run-off election. Well, to make a long story short, I GOT A CALL FROM BARAK OBAMA! That's right, the president-elect called me. The only problem was that I couldn't get a word in edgewise, he just talked and talked as if he wasn't listening to me.

Well, at least he called. I wonder if I need to put him on my holiday card list now.

Hey, Atlanta, let's do the math

Many technical communicators cannot afford to attend a conference every year, not because of the registration fees, but because of the associated travel and hotel costs (which typically exceed the price of the conference). The STC conference will be held in Atlanta in 2009, and for local good old boys and gals, this is a great opportunity to attend the premiere conference for technical communicators without having to cover the travel expenses.

If you are not already a member of STC or if you are wondering if you will renew, look at the additional savings you get if you attend the conference as a member:

Non-member Early Bird registration: $1095

BUT:
Classic Membership: $175.
Member Early Bird registration: $795
Total cost: $970

By joining or renewing your membership, you save $125! And you get all the other benefits of STC membership.

I can't remember any other time when our profession has had so many exciting opportunities and challenges--this is the year to ramp up those professional skills and contacts. I hope every technical communicator comes to Atlanta for the conference, but we local professionals should take advantage of having the conference right here. Go to the STC Web site and join or renew your membership today.

Better me than Fido?

Every morning I see the following message on the body wash container in my shower: "Not tested on animals."

I'm glad that they didn't abuse animals to develop my soap, but on the other hand, it means I'm getting it before the dog does. I like that they don't do "experiments" on animals, but I also think that at the very end, right when the scientist is about to give it the "OK, Mike can use it" seal of approval, he would say, "You know, Fido here could use a bath. As long as I think this is safe enough for Mike, why not give the old pooch a scrub before signing off on this."

Truth is, Fido probably could use a bath.

Will Write for Metamucil

I almost started today's blog with "I'm getting old" and then decided that's not true. I am old. I tried my best not to get old. Physically I tried to avoid it by drinking and smoking and not exercising, but that didn't work (at least not yet). Professionally I have dutifully tried to keep up with the trends: I DITA, I Wiki, I blog, I tweet, I have a translator on my blog, and I have a page on FaceBook. I also have a pair of bell-bottoms but that doesn't make it 1970 again. (I don't really have a pair of bell-bottoms, that was just a literary device.)

About nine years ago, I was giving a talk on Web page usability at a CDC conference and a gentleman in the audience asked a question about how to make his health Web site for young African American males more engaging. I thought about it for a minute and then gave him my best counsel: "Don't take the advice of a fifty year old white man."

I am feeling the same way about technical communication in general these days. I am steeped in a literary world view that is grounded in the static page. I grew up reading books, papers, and magazines. I did not work with text on a computer screen until I was in my forties--and then it was green screen command-line word processing where you had to actually print the document to see what it looked like.

Keith Lang dedicated an entire blog post to a rather blistering critique of my latest column in UXmatters. My biggest "ouch" response came to this paragraph.

The article is like bad help. It’s too long. It’s too dry. It has no narrative, and it’s written for the kind of people that like to read manuals. I’ll admit it, I’m one of them, but I’m aware I’m the small minority. The pictures are boring. It has no characters, story, or SEX to it. And it’s text, text text.

Not surprisingly, Keith is quite a bit younger than I am, but it reinforces a truth I have come to accept: I am ill equipped to write for an emerging segment of the marketplace.

But that doesn't mean I'm used up like a worn-out number two pencil stub (my favorite simile these days). But it does mean that I need to reevaluate where and how I add value.

For example, Keith included what he called a"nice example" of a built in help video:
It is very nice. A couple of questions: What does this video do to your translation costs, assuming it has a sound track? And how well will the image of a young woman with exposed bra straps play in conservative cultures such as with Muslims? (See my earlier blog about the BBC article in English and Arabic.) Maybe Keith isn't thinking about global markets. After all, his blog does say about comments: "here's how to have your comment approved and published: - Make it in English (my only language)." Sort of says, "If you don't speak English your voice is not welcome here." So maybe part of my emerging role as an elder is to remind the Keiths of our profession that cartoons and cool need to translate across wide cultural boundaries, and input needs to be open to diverse cultures, some of whom might not write your language well.

I'm not picking on Keith, I have have encountered similar gaps before with designers I know well and I respect a lot. People like me, that is, ones with an ingrained world view of communication-as-words, need to bring in designers who have grown up with a more interactive experience with communication channels. If nothing else, they are more like the market place than I am.
But this does bring up the core question of this blog: What is the role of older technical communication professionals like me?

Well, I don't think I should just shut up altogether (although I should shut up a lot and listen more--but that's been true for forty years). But what value do I bring to the party that could help my younger colleagues be even more successful with their innovations? Some suggestions:

• I think I understand the business model better at times than they do. I can help them focus on how their ideas add value not only to the user experience but to the success of the enterprise that pays their salaries.
• I value sustainable processes more than they do. I can help move their innovative ideas into the factory and make those nifty things they do scalable.
• And my somewhat conservative technical communication style probably still plays better in highly technical, complex problem spaces like configuring firewalls than a video or a cartoon would. And that style translates efficiently across cultures and languages.
  

I should probably try to get a job with a high-tech global company.

The taxonomic conundrum of chicken salad

Let's say your cookbook has a section for chicken dishes and one for salads. Where do you put recipes for chicken salad?

Actually this is a relevant topic for me for a couple of reasons. For one, Atlanta STC is putting together a cook book for the upcoming Summit in May.

Secondly, I am working on refactoring current Help and user guide topics into a new, unified format that has proscribed topic containers for the TOC. The problem is that the navigation pane in the product's user interface has not been built around these TOC guidelines. Hence, certain tasks that the documentation guidelines would call Administering the product have been placed in a section called Configuration in the product's navigation tree. Oops, the documentation navigation guidelines include a container called Configuring.

We need to figure out the right balance between what expectations we think our product navigation creates and what would make us consistent with other products we might need to integrate our information topics with.

I'm tempted to take the solution of going to our developers and convincing them that where ever possible, they should match the product navigation guidelines to the documentation guidelines that have been proscribed.

Please, someone talk me out of this :-0

Veterans Day

I rarely think of myself as an honoree on Veteran's day, but I got an e-mail from my company's VP of Diversity this morning thanking me for my service. At the time, it felt more like servitude--1969-1972 were not tranquil years, and as a young man I would have preferred to have been growing my hair long and hanging out in coffee houses. And had I not flunked out of college in 1969 I probably would have been.

As it was, I was in the Army and hating it. For the life of me, as I look back, I can't figure out why. I was going to the Defense Language Institute in Monterey, California, and after that I spent an exciting tour in Ethiopia, followed up by a stint in Washington DC where I met my wife. I had the time of my life and met some of the most interesting people I have ever known. (When there is an active draft going on, the military ends up with the entire spectrum, including the ivy league elite who couldn't escape low lottery numbers--I went to Arabic school with the son-in-law of Supreme Court justice Brennan along with a couple of Yale grads and a really funny guy from Penn State. Me, the college flunkie!)

After 9/11, I dug out my old stripes and GI-issued name tag and I have used them as my cube name tag ever since. I looked at them this morning as I came in and felt a quick moment of self-satisfied veteran pride.

I served :-)

Now I understand

I have always liked the "feel, felt, found" method for answering objections. "I know how you feel, I felt the same way, and then I found..." I experienced it in an internal conversation with myself last week.

I have resented the pressure to write for "ease of translation" for a long time. For one, I felt it really meant "ease of machine translation" because the job of a human translator is to understand the rich metaphors and idioms that create meaning in the source language. Secondly, I felt that it took plain, easily understood explanations and turned them into bland, generic prose. Clear phrases like "change firewall rules on the fly" had to be rewritten to "change firewall rules without having to restart the system." I understood the economics of it, but that didn't mean I had to be pleased with it.

And then I put a translation application on my blog site. Now I find that I want to write so that it can translate my blog as accurately as possible. I now examine my every word wondering how the translator will interpret it. What made the difference?

Probably it has a lot to do with the fact that it was my decision to increase the global access of my blog. It is not that I expect a lot of international readers; it was because I wanted to be global. And now the translator is my tool, the only way I can afford to meet a diverse global readership.

The point of this blog is not about globalization. It is about getting people to accept change. The more we can make the decision at the level of those who must make the change, the more that change will be accepted. Just being a writer for IBM (International is our first name) wasn't enough to make me accept writing for an international audience--it took me putting a free Google widget on my blog site. So when confronted with the need for change, we need to find a way to personalize that change in some way within our smaller world that we can see and understand. And in this case it means not ending my blog entry with an idiom like "eating my own dog food." I can only imagine how that will translate.

It's more than just the words

A friend of mine sent me a link to an article on the BBC website. You can get the gist of it from the image below (click image to enlarge it):

In the oddest of coincidences, I had read the article the day before on the BBC Arabic version website. You can get the gist of it from the image below (click image to enlarge it):

Aside from the language translation and the shift from left->right to right->left, one other big difference is obvious.

It proves to me that the BBC is very savvy and understands that there is a lot more to localization than just translating the words.

The easy question is what did they change? The next question is why did they change it?

Going Global and oh so Web 2.0

I added a translation widget to my blog. Scroll down the navigation pane on the left to find it. View this blog page in the language of your choice.

I've started trying to pick up my Arabic again (I was a translator for the Army Security Agency about a bazillion years ago) and that has gotten me interested in online translation tools. This particular widget has a nice mouse-over feature that lets you see the original text. Try it.

Time change

I hate it when the time changes from daylight saving time. It's such a pain to get up at 2:00 am to reset my clock. They should make it occur at a more convenient time.



What!?!?

Step away from the keyboard!

You know what never works out well? Letting technical communicators get involved in legal documents. When I do it I end up in tears; when I watch others do it I find myself shaking my head and saying "Bless their hearts."

We want it to be clear; lawyers want it to stand up in court. I've come to accept that there just is not much overlap in that Venn diagram.

Solution? Let them have their way.

Alphabet Soup--the comeback

I have decided to start including my CPT (Certified Performance Technologist) credentials after my name again. Click on the CPT logo in the left column to read a more extensive description of what being a CPT involves. I've had this certification for about eight years, but quit using the credentials a while back. I think I felt a little pretentious putting that many letters after my name. Aside from coming to accept myself unapologetically as the credential junkie I am, there are some other reasons I have chosen to do resume their display.

User assistance as performance support

As a writer (and I still see myself as a writer) there is a tendency to think of Help and other user assistance strategies as content, something to be packaged into containers and taxonomies. But Help is performance support, something to be delivered in the context of a user trying to do a task or accomplish a goal. Posting my CPT is a constant reminder to myself about what I really do.

Certification as a professional differentiator

I have been involved in the STC's efforts to evaluate whether our profession would be well served by a certification program, and I have become convinced we would. So showing my current certification is a way to support certification as a professional strategy. And in a tough economy, instead of standing on the side of the road with a sign that reads "Will communicate technically for food" I can now advertise "Will support performance for food."

Heck, for a beer I'll do both.

My Recession Strategy

Yikes, the economic news is certainly scary these days. So what do you do if you think layoffs are coming?

Get into the top third

Every boss right now is making a list, real or mental, that focuses on which employees are in the top third and which are in the bottom third. Get into the top third of that list by doing the following:

• Add value in the areas that your boss will be evaluated on.
• Make your boss's job easier/more pleasant.
  

Some examples for adding value:

• Is your boss tasked with off-shoring certain aspects of the work and you've been the lone voice of reason in the wilderness pointing out the foolishness of such an endeavor? (Substitute the appropriate goal: implementing DITA, going to a new CMS, etc.) Step one: Shut up! Step two: Find ways to make it work.
• Yeah, yeah, we're all about the user, yay user, but take a look at ways to cut development time, production costs, etc., and let your boss know what you're doing there as well.

Some examples for making your boss's job easier or more pleasant:

• Be happy. Seriously, people would rather work with happy people than with chronic whiners.
• Having personality conflicts with someone? Get over it or at least appear to. If someone is habitually whining about you and you have nothing bad to say in return, you make the top third, he makes the bottom third.
• Having legitimate work conflicts? Stay positive and work through the solution.
• When discussing issues with your boss, have a success path defined--don't tell them how the project will fail.
  

Remember, in a layoff, the decision as to who goes and who stays will be made for some rational reasons and some emotional reasons. Cover down on both.

One more thing...

Oh yeah, start going to your local STC chapter meetings. Never hurts to fire up the network before you need it.

It's a Coyote!

It's never too late to have a happy childhood.

As a boyscout, I was fascinated by the section in my handbook that talked about taking plaster castings of animal tracks. I imagined myself with my field kit, crouched over some track and painstakingly capturing it.

I guess it made my subliminal bucket list because a few weeks ago I went to the craft store and bought some plaster of Paris. In the meantime, I've been assembling various tools I would need and putting them in a canvas bag. This Saturday I ventured into the fields and riverbanks by my house to try to find a suitable paw print.

There it was in the red clay, a solitary paw print of what I hoped would be a coyote (we have them in my neighborhood). In my heart, I realized it was probably Cowboy, my neighbor's dog, but a print is a print and I needed the practice. I flicked and blew the debris out of the print, paper-clipped my cardboard strips around it to make a mold, mixed the plaster with water, and carefully poured it into the mold. To my astonishment, the flimsy mold held up. I dutifully let it set for forty minutes and then pulled it up. After a bit of a struggle, it came. It took a while to get the excess clay off of it. (I looked like a CSI guy with my assortment of brushes and toothpicks carefully carving the plaster casting out of the impacted clay around it.)

It was a curious view of the animal, a worm's eye view, if you will. The reverse casting was not like the track, an impression going away from me; it was a three-D impression of the paw coming at me. This is what it looked like if you had been in the ground when the critter walked over you.

I got it cleaned up, and it is a paper weight on my desk at home. I anxiously went to the web this morning, and hoping against hope I googled coyote track. To my amazement, there was a picture comparing dog tracks to those made by a coyote--mine was not the splayed-toe impression of a dog. It was the tightly grouped, long clawed impression of a by-gawd coyote!

I'm too old for the merit badge, but not for the thrill.

Help!

I'm looking for eye-tracking studies that specifically address how users process embedded assistance. For example:

• Where do users' eyes go when they're stumped?
• If inline messages or Help are provided, when do users focus on them?
• What is the optimal placement for instructional text relating to a page or field?

I have no shortage of my own opinions and anecdotal data on these things, but I would love to know if there are eye tracking studies that could provide that type of empirical data.

Also, I am NOT looking for eye-tracking of content-focused web sites or search results. Those I've seen. I'm interested in applications or forms and how users process inline Help.

New Column

I have a new column out today on UXmatters.com called Use Cases for User Assistance Writers. The subtheme might be "Everything old gets new again at some point."

Quote of the week from Lisa Pappas at the STC board meeting this weekend. "Verbing weirds words."

Good news, bad news

Language! What a tricky thing--and once again I am in awe of the ability of technology to make me smarter. I used the word "bellweather" in an email to someone today and my spell checker informed me that it should be "bellwether." I had always assumed that a "bellweather" referred somehow to a bell that rang in strong wind and therefore was an indicator of impending weather, and hence its more metaphorical use as a trend indicator. The corrected spelling made me doubt whether (no pun intended) or not I understood the word so I cut and immediately pasted it in my Wiki search widget on my default browser page. Oh my:

A bellwether is any entity in a given arena that serves to create or influence trends or to presage future happenings.

The term is derived from the Middle English bellewether and refers to the practice of placing a bell around the neck of a castrated ram (a wether) leading its flock of sheep. The movements of the flock could be perceived by hearing the bell before the flock was in sight.

Well, the next time you're thinking about whether to be a leader or a follower, you might want to keep that castrated ram thing in mind.

I should have paid more attention in geography class

Well, I finally ran out of bottled water and canned beans, so I emerged from my duct-taped basement ready to fight for my life and country against the Russian invaders. Well, am I embarrassed! It seems there's a whole country somewhere also named Georgia, and it was invaded, not my state. I need to become more global.

Collaborative Walkthroughs

A quick shoutout to Miranda Bennett for her blog http://www.mirandabennett.com/onwriting/?p=23 on collaborative walkthroughs. Can't afford usability tests, team building exercises, or training for your writers? Try these walkthroughs and see if you don't get addicted.

Congrats to Jimmy Wales

Fresh from STC News and Notes: "Jimmy Wales, the founder and creator of Wikipedia, has been selected as STC’s 2009 Honorary Fellow."

I expect this announcement to create its own share of controversy. STC's top honor going to someone who cuts technical communicators out of the loop?

Well, we're out of the loop only if we choose to be out of the loop. One way to define Wikipedia is as a technology intervention to connect people with answers to people with questions. Sounds like technical communication to me. I think Wikipedia is an icon to where we are going as a profession: less about grammar and style guides and more about presenting information as performance support; less about creating content and more about orchestrating the distribution of that content.

It doesn't mean we will quit writing, quit editing, or quit publishing. It's just that like the passing of the literary clergy of days gone by, we are no longer the exclusive keepers of the book.

But just in case Wales' honor adds to your angst already brought on by offshore non-native writers, machine translators, mechanical spelling and grammar checkers, and you're wondering about the need for technical communicators--there are a few areas we can focus on that will let us add value above and beyond our commodities that are getting eroded:

• User analysis as problem analysis and information as performance/decision support, i.e., what does the user need to know in order to make an informed decision at this point in her work flow
  
• Dynamically generated user assistance (If Amazon.com can figure out my reading preferences and Google can guess what ads I'm most likely to respond to, why can't my Help track where my user has been, what system configurations she has set and give her tailored Help. Why does my Help say "If you are in Routing mode do this; if you are in Transparent mode do that." Why doesn't the application tell the Help what mode the user has configured and deliver a dynamic Help page that gives only the appropriate information?)
• Integrating our communication skills to improve the design and development process, as in use case development

At any rate, job well done, Jimmy, and thanks to a forward-looking selection committee for making Mr. Wales an Honorary Fellow.

Errors and Humanity

A recent article by Scott Abel on Content Wrangler about TEAL, a group whose quest is to correct the typographic errors of others, got me thinking about errors. That vector is intersecting with some reading I've been doing lately in "Orality and Literacy" by Walter Ong (at the suggestion of someone to one of my earlier blogs).

First of all, we sometimes misuse the word "typo" as in typographical error. According to Wikipedia, "A typographical error or typo is a mistake made during, originally, the manual type-setting (typography) of printed material, or more recently, the typing process. The term includes errors due to mechanical failure or slips of the hand or finger, but excludes errors of ignorance." Checking other dictionaries supports that definition.

The mistake discussed in the Content Wrangler article failed to meet these criteria on two counts: (1) The mistake occurred in a hand-written sign, which would make it a chirographic error and (2) It was not a mechanical slip; it was a mistake in applying the apostrophe rule.

Scott and I had a fun discussion and I'm not blogging to belabor my point; it's just that I have a genuine interest in the different ways we make mistakes and would like to explore it a bit--not sure this will go anywhere useful. Here's my starting taxonomy:

• Typographical--More or less mechanical slips such as wrong letters or metatheses, such as my habitual typing of "form" when I mean "from."
• Oral--Where we use homonyms inadvertently, such as "there" for "their" or "too" for "two." Almost a mechanical slip, but not really, and one not caused by ignorance but rather by the hasty grabbing by our mind of a spelling from the wrong box but one located near the correct box. I also include subject/verb disagreements caused by singular words that sound plural, such as "My interest in this area are clear."
• Drops--Where a word that was in the writer's head just never makes it to the page, e.g., "I've been meaning write you..." I think this is caused by the writer's thoughts getting ahead of his fingers. It's often missed in rereading because of the Gestalt of filling in blanks based on knowing the broader context.
  
• Spelling--No accident, the writer didn't know the correct spelling.
• Punctuation--No accident, the writer thought there should be a comma and there really should not have been.
• Grammar--Breaking the rules that define conjugation and inflection.
• Usage--Wrong word for the context, such as , uh, typo to describe a punctuation mistake on a hand-written sign (OK, I am belaboring the point).
• Factual--What the writer said can be refuted by evidence or authoritative sources, e.g., "There are 51 states in the US."
• Logical--The structure of the discourse and the premises do not support a conclusion.
  

The last three--usage, factual, and logical--are major errors because they lead to miscommunication. When the others do not miscommunicate (and sometimes they do), they are minor infractions that might reflect badly on the writer but do not mislead the reader.

I think people worry too much about the minor infractions in instant messages and blogs. How often do we get an IM with a typo or oral only to get an immediate follow up like "oops, I meant two not too :-0 " Personally I think the error is part of the oral nature of IMs and the correction does more harm by interrupting the flow of the otherwise spontaneous conversation. In my comment to Scott's article I wrote "technical communicators at their worse." Oops , I know it should have been "worst" but that's the nature of a free and spontaneous engagement using language.

I'm not advocating that we get lax in our own standards, particularly as they apply to our professional, written communications. But let's be more forgiving of these patterns (yes, that's what they are, more so than mistakes) when they occur with others. Just because a restaurant can't get the menu right, doesn't mean they can't cook. Put the red pen away and enjoy your meal.

Cognitive Tools

Tom Johnson has a post on one of my favorite topics, Tools. It's not that I'm a tool fanatic, it's just that I'm fascinated by how they interact with our creativity to shape the products we make. I've long been an advocate that teaching technical communication without teaching tools is like teaching art students about painting without talking about brushes.

An aspect of tool use and evaluation that sometimes gets overlooked in tool discussions is to what degree a tool helps the user think better. The academic phrase for tools that do this is cognitive tools. Cognitive tools are closely related to performance support tools, but I draw the following distinctions:

• A performance support tool manages workflow and pushes data to the user based on the programmed expertise about the job domain the tool is programmed to support. A troubleshooting script is a performance support tool. I can use it to solve my problem but not get any smarter about troubleshooting.
• A cognitive tool helps me think about the problem space or job domain.

Whereas a performance support tool typically answers questions I ask, a cognitive tool helps me come up with questions I would have never thought to ask. Performance support tools help me do; cognitive tools help me understand.

I like tools that have a bit of both. For example, a word processor is typically a performance support tool. It lets me enter and edit text efficiently. But I often switch into Outline mode partway into writing a document and look at just my headings. All of a sudden I can see structural flaws or problems with flow that I had not noticed while immersed in the content. I can then shift topics around until I see a structure that feels right. It is the tool's ability to tap into my intuitive processes that gives it a value above its ability to enter, copy, paste, and spell-check.

Now that I am sensitive to this intuition support aspect, I am seeing all kinds of examples. Watch the video embedded in a blog about the future of the Web to see how faceted metadata searches can tap into an intuitive need to understand more but when you can't articulate the question. Warning: the initial example assumes that the reader has a well articulated question, but watch later examples as the tool helps a vision of possible relationships emerge.

Pivot tables in Excel (or pilot data tables in Symphony) have the same ability to let me kind of "poke around" in the data until I stumble on interesting relationships I had not thought to inquire about.

Ours is a very rational culture that holds a strong belief that good documents start with a clear outline, good training starts with crisp objectives, and good design starts with exhaustive requirements.

I think real projects start with some unstructured poking around that eventually converges on a clear vision of what needs to be done. Furthermore, a goodly portion of that poking around has to be done in production mode (including production tools).

So I would add a criterion to evaluating tools: Do they support cognitive activities such as analysis and relationship modeling; specifically, can they support "what if" experiments that are easily reversed if they go nowhere useful and on the other hand can be easily implemented into the production model if they prove useful.

Why I Hate PDFs

Not all PDFs; that would be over the top. I just hate user manuals that are distributed as PDFs.

1. They are mainly used online so why the artificial page constraints? I'm in the middle of a topic and all of a sudden there is a page break--not because of a topical shift but because had it been printed on 8.5 x 11 we would have run out of paper. News flash: I didn't print it and I was not running out of paper.
2. Don't hand me that "search online and then print what you want to read malarkey." If that was the plan, there would be only one set of page numbers, not a "paper" page number and an "electronic" page number that make me guess which one the printer dialog box is asking for. I know you can match them up, but most writers don't; it violates "good book design" to start counting at the beginning. That's why we all know that if the page number is a Roman numeral, there is no useful content on that page.
3. They are laid out as if they were going to be printed--and printed in duplex at that! If the company is too cheap to print, then at least make it easy for Joe Schmoe to print and stop with the recto/verso page layouts.
4. They carry so much book overhead: book front cover pages, book back cover pages, inside cover pages, chapter cover pages. It takes me three clicks to get to a topic that actually says something.
5. There are too many of them and they are named after obscure roles--none of which describe me. I've never met a system administrator, never saw the job title anywhere I worked, yet there are a bazzilion guides out there written for that person. I always suspect that what I need is scattered across three different guides. Give me a single source where I can ask my question once and get all my possible results.
6. They just scream, "Books are what I know how to write; books are what you get."

User books died; if they had value in that form, companies would still print them and users would buy them. Yet PDFs still hang around like pathetic home town sports fans after the team has moved to the West Coast. Quintus in The Gladiator says "A people ought to know when they've been defeated." PDFs should get the wake-up call.

[Yes, I quoted The Gladiator. It's one of my favorite movies; you might want to take that into consideration when deciding how much credibility to give my opinions.]

Same Topic, Different Content

The last area of reuse is where a topic could be reused if certain snippets could be changed. Most of us know this as conditional text; DITA I believe calls it conditional processing. I'm not a tech comm historian, but I would wager that this is the oldest implementaion of reuse other than copy and paste.

The most common applications are where some snippet, phrase, or instruction would be different depending on the OS or reader role. For example, have an instruction say ,"Click Start > Shutdown" for the Windows version of a manual and for Mac say, "Oh get over yourselves." (Sorry, couldn't resist that one.)

In DITA, you do this with ditaval properties and a separate .ditaval file that implements the conditionality when the ditamap processes the document. The main tip I have on that is to comment in the ditamap what ditaval files to run for what conditions. Sometimes we forget that others must follow us and will need the path blazed (also, when we come back to that file 12 months later we won't have the foggiest idea what we did).

Conditional text can let you get a lot of reuse out of instructions that have slightly different commands within a few steps. It can become a slippery slope, however, that can take you from writer to programmer if you're not careful. I have heard of some conditional strings in that no one could untangle after the original author ever left. The conditional text was trying to deal with multiple products and multiple audiences at the same time, or something like that, I believe. It certainly made editing and testing a challenge as well.

This ends my series of blogs on reuse. It's been helpful for me to reflect; thank you for your patience.

I made this joke up

An editor, a tech comm manager, a professor of technical communication, and a techical writer go into a bar. The bartender asks, "What are you having?"

The editor says, "At the moment nothing."

The manager asks, "What do you have?"

The professor asks, "What are others having?"

The tech writer says, "<step><cmd>Give me a <uicontrol>beer</uicontrol></cmd></step>"

Same Content in Many Topics

That last side trip about which voice to use still has my head woozy and so I need to get grounded again by talking about reuse.

Reusing snippets

Another scenario in reuse is where the unit of reuse is smaller than an entire topic. Common examples include:

• Product names
• Notes, Warnings, and Cautions
• Descriptions of common user actions
• Any sensitive text that has been vetted

There are several advantages to reuse in the case of snippets like these:

• Creative productivity--By this I mean not having to make up text time and time again. I differentiate this from productivity gains from not having to type the same text time and time again, because I'm not convinced that it takes less time to insert a cross reference than it would take to type it anew. The savings, in my mind, come from not having to recompose it each time.
• Revision efficiency--Oh yeah, when marketing decides the product is now WormBuster XL rather than WormBreaker: edit once, change many.
• Control--After two hours of arguing with legal and marketing how to warn the user that changing advanced parameters could crash their system if they make a typo, make sure that the vetted text is used everywhere.
• Consistency--If the drop down for selecting port protocol on this screen works just the same way as it works on 11 other screens, it is easier for the user to process and remember the instruction if it is the same for all 12 screens.

Guidelines

To reuse subtopic elements, you need a composition environment that allows you to identify components and insert them in topics as objects. In DITA, this is easy since DITA is a semantic markup XML implementation. Every tag has an ID attribute, so every element that can be tagged can be IDed and subsequently shared. The tag in DITA that allows you to insert content from another topic is called the content reference [conref]. Essentially it is a tag in one file that points to a tag in another file.

Ubiquity

The big caveat in DITA, however, is to use ubiquitous tags, that is, elements that can be used the most widely within the rules of the DTD (the rule-keeper of structured writing, essentially the defining document that says what can be used where).

For example, all DITA topics have a short description [shortdesc], but a topic can have only one [shortdesc]This means that if you want to reuse that short description elsewhere, you must give it a tag other than [shortdesc]. The phrase tag comes in handy there. You would tag your short description like this:

[shortdesc][ph id=sort_search]Use this dialog box to sort the order of your search results.[/ph][/shortdesc]

That way, you can grab that phrase and reuse it in other topics, even as the short description in other topics.

Corral your sources

A good practice is to create special files that contain your conref'ed phases or components. That way you do not have to go looking for them trying to remember what topic was the source of that well-phrased warning. It is useful to have specialized conref files, for example, a file for product names, a file for warnings and alerts, a file for UI components, etc.

Probably the best practice in this regard is to develop the discipline that the first time you decide to conref a phrase that you have already used in a topic, pull that phrase out of its original topic, put it in a conref source file, then conref it back into the original as well as the new topic. Not only does this preserve the integrity of single sourcing, it lets you rethink how you want to word that element now that you are throwing it into the reuse pool for others.

Avoid restrictive wording

This is pretty much the same guideline that we had for topics. Think reuse ahead of time. For example, if you are documenting a UI component that sets the source port for a firewall rule, and you know that same component is used elsewhere to define destination ports, avoid using the restrictions "source" or "destination" in the instruction. The user should pick that context up from the topics themselves, don't restrict the reuse of the instruction by repeating that restriction there.

Guess who's talking

A little side trip again away from reuse. I was visiting with my sibs in Florida and was picking up a bar tab (since I am typically the major contributor to the total). The waitress delivered me two credit card tickets, one labeled "Mine" and the other labeled "Yours."

So which one do I keep and which one do I give back to her?

Had she handed them to me and said "This one is mine and this one is yours," I would have given her the one about which she had said "This one is mine." But because it was in writing, I was inclined to keep the one that said "Mine." I guess because as I read it, the voice in my head was my voice and I identified "Mine" with me. But the "Yours" didn't work in that scenario since I wasn't talking to anyone other than myself. I think I kept "Yours" and gave her "Mine" not feeling any too comfortable that I had gotten it right.

But boy, what a lot of thinking just to figure out which to give back of two documents that would have been the same except for the label that tried to differentiate them.


Why not "Customer" and "Merchant"? like most do? That is not ambiguous.

Or even "Give us one and keep the other."

Or don't label either. Then if I asked which one she wanted she could say, "The one with the big tip on it."

Side Track

I just generated a PDF of a draft of a user guide I am working on. I've included the obligatory front matter and Chapter 1 starts on the 23rd page.

And we ask why users don't read our stuff.

:-(

Types of Reuse

Scenarios of reuse

There are four scenarios within which reuse can occur:

• Same content published in different media
• Same topic in different documents
• Same content within many topics
• Slightly different content within one topic

The first is very elementary, for example, outputting the same document as a chm, web help, and as a PDF. This is the equivalent of changing the paper in the copier from canary to goldenrod while running the office Christmas party flier and saying you are reusing content. Not very interesting and I'm not going to talk about it.

Same topic in different documents

The next scenario, using the same topic in different documents, is perhaps the most common and most efficient way to reuse content. There are a few requirements to reuse content in this way:

You must write modular, stand-alone topics. DITA and Information Mapping are both good models for writing modular topics. The usual restrictions apply:

• No transitions from or to other topics, such as, "As we said earlier..." or "In the next section..."
• No restrictive references that limit reuse
• No embedded links that create dependencies with other topics

The first two requirements fall on the shoulders of the writer. Avoiding transitional phrases is easy enough; it's the need to avoid restrictive references that requires foresight and new sensitivities. For example, many writers would write, "Click Configure > Firewall > Access in the navigation pane on the left," without a second thought. On second thought, however, that navigation pane might end up on the right if the UI is localized for Arabic. You can't just hope the translator would know that. Other restrictions might include mentioning specific products in a topic that might be applicable beyond the product you're writing for. For example, the conceptual topic "How Access Rules Work in the Sentry 2X" might also apply to other product models as well, so the title "How Access Rules Work" would be less restrictive. If the reader is in a document called "Sentry 2X Configuration Guide" she won't wonder if the topic applies to her.

The third restriction, including links that create dependencies, is similar to the second, avoiding restrictive references. I separate them because your composition tool can help in the case of links. In DITA, for example, the link between Topic A and Topic B is not coded into Topic A or B. That relationship is defined in a ditamap, a third file that exists independently of the the two topics. This enables a writer to take Topic A and not have to take its link to Topic B (meaning the writer is free to take A and not B). If you are serious about reuse, you need to have a composition tool that lets you define links independently of the topic content.

Use ubiquitous graphic formats. The best format for graphics is .jpg if you wish to maximize their reuse across multiple media.

Be able to save the topic as a standalone file. Essentially, this establishes the portability of the topic. And while we are on the subject of files, get used to naming your files in all lowercase and without spaces. All operating systems can deal with that convention, whereas some cannot handle mixed case or spaces.

Pull discrete files into a document by pointing to them. Your system needs to build documents using structure files, that is, files that define what content to include, but do not contain the content itself. In DITA, this is done with a file called the ditamap. It points to topics and other ditamaps, defines sequences of topics, any parent/child relationships, and can contain relationship tables to define how topics link to each other within the context of a particular document. Metaphorically speaking, it is the blueprint that makes a particular set of content legos a Ferris wheel and another set (including many of the same legos) a firetruck.

Next blog we will discuss using the same snippet of content across multiple topics.

Reuse: A side trip

Before continuing with the technical details, a brief look at reuse from both sides.

First listen to this: http://www.youtube.com/watch?v=bcrEqIpi6sg (Joni Mitchell singing "Both Sides Now" in 1970)

And then to this: http://www.youtube.com/watch?v=tKQSlH-LLTQ (Joni Mitchell singing "Both Sides Now" 30 years later

It's one thing to write the words; another thing entirely to have lived them. Enjoy.

Architecting for Reuse

In the year 2000...

OK, Late Night fans imagine me--Conan O'Brien like--dressed in black with a flashlight under my chin chanting the above heading (which Conan continues to use even though we are long past 2000--it just has a nice ring to it).

By the year 2043 I predict that we will have written every sentence that we need in order to document anything that can get invented. At that point, it will be unnecessary to write any new sentences, and our job will be to assemble those we already have to meet the new needs. We will be in the age I now dub "Semantic Green" because the emphasis will be on applying resources to the reuse of what we already have versus creating wasteful, redundant prose. (By the way, music achieved this status in 1978; there has been no new music after that year.)

Some of you may say, "Mike, you're kidding," to which I reply, "Well, duh, of course I'm kidding."

Seriously, folks...

After hearing the reuse and content management talk now for years, I have suddenly found myself immersed in actually doing it. (Oh, I've dabbled with conditional text over the years, but that was the extent of it, and I was never in a situation where it seemed to be that important.) Although my prediction above was tongue in cheek, it describes a reality that is upon us today, namely, the purposeful reuse of content (versus the opportunistic reuse of content). The latter is epitomized by the phrase "Why reinvent the wheel" and the former by the phrase "Let's invent one wheel that will fit not only cars we build today but cars we might build tomorrow (or might be building in another plant right now that we don't know about)." OK, the latter phrase got a little wordy.

So I'd like to start a series of blogs for awhile that explore not only what it means to write for reuse, but also what it means to plan for reuse. And specifically I would like to examine what the role of an information architect is when it comes to reuse.

A few disclaimers up front.

• I have drunk the DITA Kool-aid to the point that I am as blue as Pappa Smurf. A lot of what I will talk about comes from my DITA perspective, but I think it applies to any composition environment that tags content. And some of what I'll talk about doesn't even need that. I might talk about DITA a lot because that is what I use, but I will leave it up to the reader to translate the principles I examine into your environment.
• Although reuse scales well within a content management system, it can still be planned for and used within rudimentary content management environments. If you can create folders, you've got a CMS. Anything above that capability is icing on the cake.

Benefits: The short list

I will talk more about benefits of reuse as we get into specific examples, but here is a quick summary:

• Write once, use many--Don't have enough writers and have that nagging feeling you're writing what someone has already covered elsewhere?
• Edit once, fix many--For all you smarty pants who said "Cut and paste does the same thing" above.
• Write once, output many--Help in a chm and User Guide in a PDF? Using RoboHelp and FrameMaker?
• Get it right, keep it right--Have a legally tricky warning or a product name that must be used "just so?"
• Translate...once--No matter how many times and places it gets used!

The ontology of reuse

After I got my PhD, I promised myself I would use that word once a year. Ontology seeks to determine what entities can be said to "exist" and how these entities can be grouped according to similarities and differences (thank you, Wikipedia). In essence, then, our first question as architects is "What stuff can be reused?"

In DITA the central component of reuse is the topic. A topic is a self-contained bit of prose and is typically saved as a single file. Infomappers can relate a DITA topic to an information map, although it is not a common practice to save an information map as a discrete file. Information maps often get aggregated into chapters or a chm before being saved as a file.

Moving up the ontology chain, discrete DITA topics can be grouped by a defining file called a ditamap. Ditamaps can arrange DITA topics and even other ditamaps into coherent documents or sections of documents. Because a ditamap is a discrete file, it can be easily reused in multiple contexts.

Moving down the ontology chain, any component smaller than a topic can be reused if that component can be identified as a discrete component and given a distinctive ID. For example, a bulleted list exists within an html tag of "ul" so that is a potentially reusable component that can be snatched out of its topic and used elsewhere. Because XML is a semantic tagging architecture, XML documents lend themselves to very granular instances of reuse. You like that alert and want to use it elsewhere? Tag it, ID it and it's yours literally for the taking.

Next blog I will talk about some techniques and guidelines for reuse, and then we can move on to how to plan for reuse as architects.

A couple of final words on Excel

Excel

My latest column on UXmatters documents many of the procedures and tricks I have discussed here, plus it includes some useful examples and screen shots. I will also be demonstrating how to build and use an Excel-based Information Model at the STC-Atlanta August 19 meeting as part of a progression on project management.

I will also show how to use pivot tables at that meeting. Pivot tables rock!

Research and the value of iterative feedback

I just wrapped up teaching a research course at Southern Polytechnic State University. Students did their presentations last night and I was delighted! They had chosen real problems at work and used their projects to make data-driven decisions. What was interesting was how many of them had found that the data they collected and analyzed challenged their initial assumptions and biases. It was also my first opportunity to use the book I wrote with George Hayhoe. The course was on an abbreviated 8 week summer session schedule, and I was expecting the worst. Major assignments were due each week, such as proposals, annotated bibliographies, data analysis exercises, and sample surveys. But I used a teaching technique I have used before, and that is to allow multiple resubmissions of assignments until the students get it right, and then give them full credit when they do. It's not unlike my barbecue technique: Turn early; turn often. In both cases that approach has reduced the instances of burned meat and failed students. I wish I had used it when I was a people-manager. Errors and misunderstandings should be anticipated as the norm and viewed as coaching opportunities, not as aberrations to be punished.

And that's how we should use the Excel Information Model. It's not about "how did we get here (and whose fault is it)?" It's about "Where are we and what do we still have left?"

At any rate, congratulations to my students for all their hard work and the excellent results they got.

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.