Re: Object-Oriented Development and Documentation

[Tim Altom <taltom -at- IQUEST -dot- NET>]

At 05:44 PM 7/1/96 -0500, you wrote:
>Hello Techwhirlers:



>In order to assist in the documentation of O-O technical specifications, the
>technical writer must have a much more in-depth understanding of the product
>and development methodologies used. This knowledge becomes sufficient enough
>so that his/her role in the project becomes less of a reactive tech writer
>and more of that of an object-oriented developer. In essence, to
>successfully document the project, the technical communicator inadvertantly
>becomes a capable O-O analyst who assumes responsibility for much of the
>grunt work; maintaining and editing the massive amounts of technical
>documentation produced. While I feel that the tasks required often stray
>from those of technical writing and move into areas of systems analysis and
>design, the presence of the writer/developer provides the team with a more
>literate and document-centric influence.

>I would not recommend this responsibility to a generic technical writer,
>since it requires a great deal of systems analysis and design and
>comparitively little writing. Although the writer does not need to become a
>programmer to participate in O-O design, a strong understanding of the
>methodology is needed to facilitate the production of the extensive
>documentation generated. The writer must have a strong interest and desire
>to learn, study, and participate in the development of the models.

>Has anyone out there had similar experiences? Do you agree or disagree with
>my conclusions?



>  Matthew Danda
>  Technical Writer
>  St. Louis, MO
>  dandam -at- 1stnet -dot- net

I neither agree nor disagree. It's just how you have to work, and it's
typical of technical communicators in your position. It's a common
misconception that our industry is staffed primarily with writers and that
they're just larking about if they're not pecking at a keyboard. Writing has
always been the smaller part of the schedule, almost always relegated to the
back seat by the up-front learning curve. Projects vary in learning/writing
ratios, but learning is almost always the bigger chunk. For example, one
project required me to write assembly/disassembly instructions for a robot
arm. Before I was done I could strip it and rebuild it blindfolded. Only
then did I spend the few hours required to document the quickest way to do it.

It's that way especially on projects that require communications with other
high-level professionals, because you can't ignore anything, and you can't
content yourself with the operator interface. You've got to pop the hood and
get familiar with the engine. It's that way with electronic devices, too.
Ever see the tech notes Intel produces, or TI, or Motorola? Same thing.

On the other hand, you have to keep your dukes up and maintain a discreet
distance. Although you may well now be a minor expert on your subject
matter, it doesn't follow that you need to enshrine it all. It's best not to
be seduced into the same trap that envelopes many technogeeks: kitchen sink
syndrome. Resist this at all costs, because yielding to it will reduce your
professional contribution to nearly nil. If all the job needs is a typist
with a good grammar checker, there are cheaper ways to produce documentation
than employing you.

It would be interesting to know just how your management intends to
"evaluate" your presence. Is this possible to do? And if it's sincerely
attempted, will it be subjective, or can it be quantified?

Tim Altom
Vice President, Simply Written, Inc.
317.899.5882 (voice) 317.899.5987 (fax)
FrameMaker support  ForeHelp support

Makers of DuoFrame, giving you online help and paper
documentation from a single parent FrameMaker document.

http://www.iquest.net/simply/simplywritten

                  TECHWR-L List Information
To send a message about technical communication to 2500+ list readers,
E-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot-  Send administrative commands
         ALL other questions or problems concerning the list
       should go to the listowner, Eric Ray, at ejray -at- ionet -dot- net -dot-