CONTENTS: 1. Does this problem sound familiar? 2. Have you ever been to a sales "shoot out?" 3. Is this an idea worth working for? 4. But, will I lose this client? 5. Did we do what customers wanted? 6. It all began with that idea worth working for.

As I've said before, businesses don't work by themselves; people work. And thing that makes people work is an idea worth working for.

Here's how this principle worked for my client and me.

============================================================ 1. Does this problem sound familiar? ============================================================

I arrive for my appointment with Carole, a product-marketing specialist who works for their VP of Marketing. In lobby, we have a brief meeting where she explains situation.

"Our 800 number is ringing off hook! We can't handle all customer's questions and complaints. We cover everything in our product manuals, but our customers refuse to read them."

"Why won't they read them?" I ask.

"Our manuals were written by programmers and engineers. Our customers are radiologists and physicians and they refuse to read them!"

"Well, I'm sure I could..."

"Wait, there's more. We're designing our new 'flagship' ultrasound imaging system, and we don't want to make same mistakes again."

I say, "Good idea! It's always best to develop documentation as you develop system."

"I agree," said Carole. "Our last effort was a hasty, last minute compromise - after we had already built system. Now, we're paying price. This time we're going to do it right. Let's go meet Greg, my boss."

============================================================ 2. Have you ever been to a sales "shoot-out?" ============================================================

We take elevator to second floor, where Carole gives me a brief tour of systems development area. She then escorts me to Greg's plush corner office with its view of Silicon Valley and south to Los Gatos. Carol introduces me to Greg, then tells him about our prior phone conversations and today's brief meeting.

After some cordial conversation, I ask Greg, "Can you tell me a little about your typical sales cycle?"

"Why? I thought you were a technical writer."

"Actually, I've spent a few years in sales and I'm well aware of need for good documentation when selling. Maybe we can write documentation to help you sell more systems. I assume you'd be interested in that."

"Hmmm..." he said. I could tell he was skeptical. "Well, OK. We take part in what we call a 'vendor shoot-out.' "Our shoot-out is most important part of getting order - if we don't ace shoot-out; we don't get sale. "A shoot-out occurs when all competing vendors bring their equipment to a specific room in a hospital or clinic. In room, there will be a real (or pretend) patient. We vendors then gather around 'patient' to demonstrate our equipment to physician and radiologists."

"Brutal!" I exclaimed. "Exactly how does that work?"

"The vendor's technicians take turns showing physicians and radiologists how their system works with patient..."

I interrupt with a question; "Do physicians and radiologists get to 'test drive' system?"

"Oh, no! The systems are so complicated that we must use experienced computer technicians for demonstrations."

"Are these technicians same programmers or engineers who developed system?"

"Yes. Unfortunately, they must be there to handle inevitable problems and crashes."

"So, when do physicians or radiologists get to try system?"

"They don't. No vendor is willing to take that risk because of possibility of a crash!"

============================================================ 3. Is this an idea worth working for? ============================================================

I ask, "Suppose you wanted to buy a new car and salesman would only let a mechanic take you for a demonstration drive. Would you buy a car that you couldn't drive your self?"

"No, but this is different. After they buy a system, winning vendor will give extensive training to buyer's technicians who will run equipment."

As I've said in many eZines, you must write stuff down.

The other day, an interviewer asked,

"How many pages you written?"

"Somewhere around 30,000 pages delivered, not including thousands of draft pages."

"You must love writing!"

"Not really."

"Then what...?"

"I don't love writing per se. I love applications. I love results. In writing, you can create, let's say, first level of reality. By writing, you can begin to give intangible ideas form in physical universe.

"Can you imagine how many people discovered secret of fire and didn't write it down? The news had to spread by 'tribal knowledge!'

"How many times did secret vanish because some fire-novice asphyxiated himself and family? How many times do think some do-gooder banned fire due to its dangers?

"It probably took eons to discover that secret - over and over!

"Eventually, I suppose, someone wrote secret on a cave wall or cocktail napkin..."

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

"Planning to write is not writing. Outlining... researching... talking to people about what you're doing, none of that is writing. Writing is writing." -- E.L. Doctorow

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Anyway, when you write stuff down, you'll eventually need to update it. (I'll talk here about large, important documents - Operations Manuals, Technical Manuals, User Manuals, or maybe secret of fire and how to control it.)

"Mike, what have you learned over years about maintaining documentation?"

Well, large documentation projects have their own "life cycle." This cycle extends from conception to obsolescence.

When you develop large-scale documents, you'll typically iterate through following:

1. Requirements. Includes definition, statement of goals, preliminary analysis, functional specifications, and design constraints.

2. Design. Includes outline definition, format definition, etc.

3. Implementation. Requires writing, editing, integration of various components, and proofing.

4. Testing. Includes verification and evaluation against requirements.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

But wait! There's another phase I call Documentation Maintenance! It begins after you deliver your documentation to your user.

You can divide Documentation Maintenance into following steps: ___ Determine need for change ___ Submit Change Request ___ Review Proposed Changes ___ Analyze requirements ___ Approve/Reject Change Request ___ Schedule task(s) ___ Review and Analyze Design ___ Write and Edit ___ Test ___ Verify against Standards ___ User Acceptance

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In these steps, I outline maintenance process, which begins when someone needs a change and ends when your user accepts your changes.

As you can imagine, changing documentation is frequently complex and may involve many people.

For example, imagine task of updating documentation for applications in complex electronics, aerospace, law, medical, insurance, etc. Or, how about updating flight-prep manual for a commercial airliner?

The maintenance process above appears linear. But again, you'll undergo many steps and iterative loops.

For example,

You may need to clarify Change Request. You may require more analysis of Design Reviews. You may need to rewrite your Standards Audit. Your users may fail to accept results, etc.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Someone, "Maintainer(s)" must do work.

This Maintainer must make changes within context of existing documentation. Maintenance people often find this most challenging problem.