Wednesday, April 29, 2009

Use Cases Are Working

Just in the nick of time, as my boss and I are putting finishing touches on our PowerPoint slides for our presentation for the STC Summit "Moving Documentation Upstream with Use Cases." The theory was that if we used use cases as our Information Development user analysis methodology, we could get involved earlier in the development process and even be able to influence design decisions.

We've had some intermediate successes but it has been hard to insert ourselves at the point in the process where we think the use cases can be the most effective. We recently tried with a project that probably comes as close to the perfect scenario: right team, right changes on the UI, good timing, etc. We had one design meeting last week where we collaborated among product developers, UI developers, information architects, information developers, and QA to understand why a user would view system statistics from the home page of one of our security appliances. The discussion last week was productive and helped form a better team vision of what the user would be doing and why (shifting the team from their normal approach of "What data do we have and how do we want to display it?").

This week the information architect ran a collaborative session where he did a sticky notes on the wall kind of card-sorting exercise that started matching "kinds of data we have" to "things the use wants to do with data" (essentially the use case titles we arrived at in last week's meeting). In a word, it was exciting!

The best part was at the end of the meeting where I asked the developers to accommodate room next to the graphs and tables for embedded user assistance to set the context for the user, based on the insights that had come out of the workshop. The developers agreed that at a minimum we could have fly-over text, pointing out that graph sizes would make real estate hard to come by.

I know this might sound trivial, but to be having discussions about what embedded assistance the designers and developers would accommodate this early in the project was HUGE! The fact that we got a concession of any type was MAJOR!

I hope those of you who are coming to the Summit will come hear our presentation and watch our demo:

Moving Documentation Upstream with Use Cases
Date: Monday, May 04, 2009
Time: 3:00 PM to 4:30 PM EST
Location: Hanover AB

How to apply case methodology and structured writing to get information developers involved earlier in the design process and to produce testable information products earlier in the development cycle.

  • Create UML use case diagrams and write use case descriptions
  • Describe a systematic process for going quickly from use case diagrams to user documentation
  • Describe the benefits of involving information developers early in the design process

Thursday, April 23, 2009

Chase the rabbit down a hole...

And find a time vampire!

All I was supposed to do was fix some capitalization issues with our new DITA build. It was picking up a title attribute it had ignored in previous versions and I just had to edit the Navtitle attribute in about 100 references.

But there was a nitty little anomaly in how the css was rendering some paragraphs. Probably just a tweak needed here. Tweak, tweak, build...hmmm no that didn't get it. Time to move on and do what I came to do: fix capitalization. Oh wait, I wonder if this other little tweak will do it.
Two hours later, still renders wrong in some paragraphs and let's see, how many more topics do I need to edit? Oh, the 100 or so I haven't touched in the last two hours.

I should know better; we all should know better. As it was, I kinda got pulled into this quick sand pool by a buddy who had already been thrashing in it for a day. But we get sucked in by this never-ending thread of "just one more thing and it should work" morass.

Lesson learned. That rabbit looks so easy to catch up with when it jumps down that hole.

Be scared of the rabbit that goes down a hole; be very, very scared.

Monday, April 20, 2009


Everytime we pass a restaurant that has gone out of business and been converted into office space, my wife comments that they must have one really great employee break room. Wow! A break room with a walk-in freezer, pizza oven, and deep fat fryer.

Howard Speck added some really great rules to my earlier blog Why did it take me so long long to learn... I especially love "Never argue with an idiot, people watching can't tell the difference." I'm having that one printed on a card and carrying it with me!

The Atlanta STC Awards banquet is tomorrow! My wife is at a business meeting all day which means I will have to get dressed in my tux all by myself.

The STC Summit starts a week from Sunday--in Atlanta!! We have a local chapter cookbook we will be selling that is a MUST HAVE for anyone attending the conference. My favorite excerpt: "You know you're a Southern technical writer if you put in a comma where you want the reader to pause...and spit."

Monday, April 13, 2009

Friday, April 10, 2009

Why did it take me so long to learn...

  • Never write an email response when I'm angry. Waiting 24 hours can mean the difference between a relationship-straining diatribe (and looking whiny) and a rational appraisal of a situation with reasonable recommendations.
  • Don't use "Reply All" to show others how smart I am by taking on [whatever, whoever]. I now limit my distribution of "I think you did something wrong" e-mails to the individual. The serendipity is that half the time I'm wrong, and I'm saved the public embarrassment of their "Reply All" that makes that obvious to the world. I took a course in grad school that helped me analyze my interaction style. I titled the summary paper that described my newly found insight "You're Wrong and I Must Warn the Others." If that describes how you interact in groups, you might want to put it on your list of "things to work on." (BTW--I'm still working on it.)
  • When having to choose between the best solution (as defined by, uh, me) and a consensus, go for the consensus. The theme of me being wrong half the time applies here as well--the compromise is not such a compromise since half the time (at least) my best solution would have been wrong.
  • Don't squander the opportunity to lose an argument.

Wednesday, April 01, 2009


It's April Fool's day and Google got me early. I took a link at the top of my email to New! Gmail Auto Pilot