Re[2]: Developer wants to take over documentation

["Walker, Arlen P" <Arlen -dot- P -dot- Walker -at- JCI -dot- COM>]

From: Arlen P Walker on 04/30/97 02:26 PM



      Interesting thread...how about we assume we know it all and start
      taking over the development of software. Wouldn't that be cool? I
      think our entire profession needs to get a backbone. Only one person
      suggested that this was insane!

      Questions like this frustrate me. It reminds me that what I do isn't
      really considered a profession. After all, anyone can write, eh?

I'm in a twisted mood this afternoon, so I'm going to put a different spin
on the issue here.

I remember a thread not so very long ago (a smile and a tip of the hat to
the illustrators who were involved in it) which arrived at the conclusion
that professional illustrators might not be used on every project because
legitimate business realities didn't permit it (time, money, and staffing
being the primary ones).

Now we have legitimate business realities being presented as a reason not
to have a writer involved in the docs. Hmm. The Goose's sauce doesn't seem
to appeal to the Gander.

FWIW, your developers may have a point, beyond the obvious one atop the
propeller. But there are, perhaps, better ways. (I haven't seen most of
this thread, so if I repeat something someone else said, just consider it
redundancy -- see my .sig -- and I'll compliment the poster's excellent
display of perspicacity. ;{>})

For Mickey, I can see a few alternatives which address the problem perhaps
a little better (Mickey's mail turnaround delay is a specious argument;
overnight delivery services prosper because they *can* manage one-day
delivery. John could grab the book, box it and get it anywhere by 10:30
next
morning.):

1) Docs in PDF should preserve the look down to the printed page for local
printing. Yes, covers and binding are still not available that way, but
perhaps the audience in question can live without them. A better question
would be if management can live with the cheapened image it presents.

2) Docs on web are instantly updatable, no lag, but no printing either. Is
timliness or paper more important?

3) (This could pair with #1) John retains the doc duty as always, but
Mickey writes a "readme" file covering the latest changes WHICH HE PUTS ON
THE NET WHERE JOHN CAN GET IT AND NO SECOND COPY. His "readme" is passed
out with the manual to cover latest changes, and John adds the changes to
the manual, after which he deletes the "readme" from the net as an
indication that this operation is complete.

4) Not sure how your net is designed up there, but is it practical to
consider you printing the doc but to a printer at the remote site?

Yes, these ideas aren't perfect; what is? But the goal here is to meet a
perceived need for faster action. (If the perception is bogus, that's
another thing. Proving it would probably depend less upon its actual
existence than upon who has the political power to make the decision
stick.)

One other note for Mickey's case. Either a) you really *are* doing a good
job supporting him, or b) he doesn't trust you and is simply spreading some
butter to make it less painful. Mickey asserts that you do a good job, but
since it's his CS rating on the line he can't depend upon you to do a good
job. One of those two statements is obviously false. You know him, I don't;
you decide which it is. (Personally, I'd simply meet this argument with the
observation that since his CS rating depends upon how well he services TIS'
customers, and yours depends upon how well you help him do that with your
involvement in the docs, your rating is indeed on the line, right there
next to his. He and his group certainly have the power -- and the right --
to spread whatever CS pain and suffering there is around.)

Now for Minnie. I'm afraid she's tripped my alarms. "You don't know what
the conditions are" has, in my experience, been used mainly to cover
ineptitude while trying to grab and hold territory. Her case may be
different, I don't know, but unfortunately her choice of words makes me
suspicious. In any case, my reaction would be to hop a
(car/bus/train/plane) and *see* what those infamous conditions are. If the
conditions *are* horrible, it should become apparent quickly.

Minnie's message also tripped alarms because, while she's asking for trust,
she's refusing to give it. (BTW, *all* needs for immediate turnaround
should be questioned. They indicate a breakdown in the system somewhere
that needs to be fixed. The fault may be on her end, your end, or -- most
likely -- a mixture of the two. Wherever it is, it needs to be found and
fixed.)

Perhaps, after getting a look at the conditions she's laboring under, you
can find a way to accomodate her. She's got a job to do, and doesn't see
what you can do to help. Perhaps you can.

(There's not a lot to go on here, but perhaps #3 above can work here, as
well.)

Both messages fairly shout that they don't trust you to be willing or able
to do the right thing. I don't know enough about the internal conditions
there to know whether those fears are groundless, but you're going to have
to try to show they are if you're going to keep working with them. If they
aren't willing to trust you, you may as well let them have the docs.

It's funny. As businesses considered adopting the JIT philosophy those very
same arguments were the ones raised. Both Mickey and Minnie see the
relationship with you as a one-way street: their butts are on the line
while you're off sheltered somewhere else. What you've got to do is
convince them to scoot over a little to make room for your butt on the same
line, right next to theirs. You need to get them to see that you only
succeed or fail because they do. Let's face it, if the docs fail them, then
there's no way you can be said to have succeeded. They just aren't seeing
that.

In any case, I'd suggest you and your boss have some thinking to do. It's
apparent that whatever you're using for a doc process isn't meeting all the
perceived needs of the customer. Maybe you need a tweak or a complete
redesign; maybe you just need to do some educating. Take a close look for
yourselves and find out.


Have fun,
Arlen
Chief Managing Director In Charge, Department of Redundancy Department
DNRC 224

Arlen -dot- P -dot- Walker -at- JCI -dot- Com
----------------------------------------------
In God we trust; all others must provide data.
----------------------------------------------
Opinions expressed are mine and mine alone.
If JCI had an opinion on this, they'd hire someone else to deliver it.

 TECHWR-L (Technical Communication) List Information: To send a message
to 2500+ readers, e-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot-  Send commands
   to LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU (e.g. HELP or SIGNOFF TECHWR-L).
  Search the archives at http://www.documentation.com/  or search and
browse the archives at http://listserv.okstate.edu/archives/techwr-l.html