Friday Mar 01, 2013

Online Help and the Epic BFFL Throwdown of the 90s

Today's blog is written by our very talented Documentation Architect, Scott T. Miller. I've watched Scott perform his writing and architecting magic for nearly 14 years. From this blog you'll get a good sense of his story telling ways that make learning from him so much fun. Enjoy!

Cheryl Lander, Oracle Communications InfoDev Senior Director

In the technical writing field, writing online help in the early 1990s was totally hip. We online help writers were ten pounds of hip in a five-pound bag. Lady Gaga had nothing on us, although in fairness she was only five years old at the time.

So when I ran into my afore-mentioned BFFL, whom I hadn’t seen for a while, we exchanged our latest news. He was in the heavily-airquoted “import” business, and I told him that I was writing online help, and I was, therefore, extremely hip.

He was not impressed.

“Online help?” he said, “You mean that stuff that comes up when you click the Help button?”

“Yeah,” I said, “How hip is that!”

Common decency prevents me from relating his comments as dictated, but the upshot was that he did not find online help to be helpful, and also if he had a will, he would have written me out of it. And here we had gone through grade school and high school together! And later we went to Guatemala together where we kinda sorta accidentally robbed a bank together!

But that’s another story. The point is, we had a history, and he was going to unfriend me, even before “unfriend” was a word, all because of a mere online documentation delivery mechanism. I mollified him by reminding him that I had rescued him from a burning tire factory, and he calmed down enough to say this about online help:

“Just tell me how to do what I want to do.”

As it turned out, I was not the only technical writer to hear such sentiments. What had happened? How could something so hip be so, as it turned out, tragically unhip?

What had happened was that the world had changed more than somewhat since the days that technical writing was about such straight-forward topics as “Lubricating Your Water Wheel” and “Proper Usage of the Butter Churn.” How to use a butter churn is not that difficult to document:

Hardware is one thing, but along came software, and writing instructions for how to use software can be much more difficult:

So, sometime around the early 1990s, the technical writing profession engaged in some pondering and reflection. (We were tired of getting written out of wills.) Previously, good technical writing was “accurate and complete,” and that was enough. Water wheels got accurately lubricated, butter got completely churned. We found, however, that documentation could be accurate and complete and still not very good.

We took another look at the online help that we were writing. It looked like this:

It was accurate and complete, but all it did was describe the software. Instead of describing the software, we starting writing about how to use it. Online help began to look like this:

This works a lot better. It lists the tasks that users want to do, and tells how to do them. Good technical writing is still accurate and complete, but it also helps users accomplish their goals. We call this task-based documentation.

After we started writing task-based documentation, users seemed to like our writing a lot more. We began to pay a lot more attention to our users, including visiting customer sites to find out how they work, and what tasks they need to accomplish.

Which brings us to the point of this story. To write documentation that meets customer goals, we need to know our customers. If you have anything to tell us about how you work, or about our documentation, which would help us write better documentation, let us know.

In case you’re wondering about what I and my BFFL have been up to in the last 20 years since the events described here occurred, my BFFL is now a lawyer (nobody saw that coming) and I��m still writing technical documentation. It beats robbing banks.

We value your feedback! You can either respond to this blog or contact Oracle Communications Information Development using our email alias:



This is a blog from the Oracle Communications Information Development team, led by Cheryl Lander, Sr. Director. She and members of her team from various functions (writers, curriculum developers, and architects) and product lines will share their approach to documentation and curriculum, all with the goal of getting feedback to improve their deliverables. We'd like to thank Joe Sciallo, UCS Tech Writer (former Sun) for pushing us into the social media world. The primary team driving this blog is called "Joe and the Blogettes"; other members include Brenda Roldan (BSS Tech Writer), Jodie Wilford (OSS InfoDev Director), Leif Lourie (SDP Curriculum Developer), and Scott T. Miller (Documentation Architect).


« March 2013 »