Re: Software documentation

[Gus Lemming <lemming -at- PTS -dot- MOT -dot- COM>]

In article QAA17887 -at- andrew -dot- cmu -dot- edu, Brian Bennett <bb18+ -at- andrew -dot- cmu -dot- edu> ()
 writes:
> At 02:27 PM 8/8/94, Glen Accardo wrote:
> >
> >
> >
> >Early involvement by tech writers can be passive.  Sitting and listening can
> >help us learn the product early, make better estimates of what we have to
> >document, and get us further along the path to "total understanding" of the
> >product.  Translation: better planning and better manuals.  When you add to
> >the mix the fact that many tech writers are computer nerds who choose to
> >write sentences instead, that we can help identify nasty spots in the
> >interface, and do a few other things -- we should definitely be in on design!
> >

> I'm not saying that you shouldn't "definitely be in on the design."  I'm
> saying that unless you are part of a mature development team (one that
> realizes that what benefits you benefits the whole product, or team) they
> are simply not going to care about your needs.  I would bet that the spec
> you are using is not useless only to you, but also to the other groups who
> use it (including the authors themselves).  It would probably be easier to
> convince the team that allowing you to manage and control the spec would
> benefit the entire team than it would to convince them that "passive"
> involvement will benefit the entire team.  In fact, if the overall
> organization is fairly immature, they'll probably fail to realize how this
> involvement would benefit you.

> If you can't convince 'em, show 'em.

> Brian


__________________________________________________________________________

Dear Brian:

What color is the sky in your world?

"Sitting and listening can help us learn the product early, make better
 estimates
of what we have to document, and get us further along the path to "total
understanding" of the product."

Yes, that's provided that those you are sitting with and listening to know of
 what
they are speaking.  How often does that occur in your job?  If the answer is
 often,
please forward the name of the person to which I can send my resume.  Almost
 always,
Technical Writers are brought into projects way too early, when there is little
 or
no information available to document.  Almost never is total understanding of a
product feasible.  Without fail any product/project that we are documenting is
way behind schedule, and the engineers and system people are freaking out
 because
their databases keep crashing, etc.; this leaves us to fend for ourselves with
 what
little information we have been able to glean from our so called meetings with
these linear thinking co-horts, and we just end up winging it and making it look
good.  Lastly, the fact that documentation is almost an afterthought for most
 project
planners, just adds to the level of frustration on our part.

"When you add to the mix the fact that many tech writers are computer nerds
who choose to write sentences instead...."

Computer nerds who choose to write sentences????  That's probably the most
 oxymoronic
phrase I have ever heard.  In all the years I have been associated with and have
 worked as a tech writer, no one has been a computer nerd.  Almost without
 exclusion, these people are former English majors, copywriters, creative,
 spatial thinking people, that because of their abilities to express themselves
 intelligently with the written word, can make decent money performing this
 incredibly arduous discipline.  Actually, most of us think of it as writing a
 giant recipe.

"I would bet that the spec you are using is not useless only to you, but also to
 the
other groups who use it (including the authors themselves)."

There you go laddy!  I take back what I said about the color of the sky in your
 world.

"It would probably be easier to convince the team that allowing you to manage
 and
control the spec would benefit the entire team than it would to convince them
 that
"passive" involvement will benefit the entire team."

Yes, and when you gather all this convincing ammunition, and even when
 expressing
your argument most eloquently, your reponse is always, as Ross Perot says "a
 giant
sucking sound."

In summary, the best part of tech writing is the "cha-ching" sound that direct
deposit makes into the savings account each week.

Yours in Employment Bliss,

Gus Lemming
fck004 -at- email -dot- mot -dot- com