Re: Documenting Object Oriented Applications

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

At 10:01 AM 7/18/96 -0500, you wrote:
>Hi Ya'll -

>I'm new to this list and have been enjoying the conversation and the wit.

>I am a contract writer and have had conversations with two potential
>clients both of whom wanted to know if I had ever documented an object
>oriented application before. I had to answer "no".

>My question is how is writing for an OOA different? When I worked in a
>corporate environment, I wrote software user manuals and from the little
>these folks have told me, I deduce that that is what they need.

>Thanks in advance for your help.

>Gem

It depends on the intended audience. If the end user of your doc is a
systems analyst, or a developer, or a simple programmer, you'll need to know
how to speak the language, which is specific to OOPS stuff.

But realistically few of us write for such an audience, because most such
people don't need a professional writer. Most of us write for software
users, and those people don't want to know an object from a predicate. Users
are interface-driven. "Show me the window and what's in it and tell me what
to do." And you, as First User, don't need to know how the engine works to
pass along driving tips. Indeed, it may be better that you DON'T know. You
have to realize that few interviewers know how to ask us reasonable
questions, so we have to guide the conversation for them. They know OOPS, so
they want to know if you do, too. What else can they ask? Grades don't mean
much. Seminars aren't really relevant. And since they don't really know what
we do anyway, the conversation could hit bottom pretty quickly.

Here's a driving tip for future interviews: Try to answer questions that
you'd rather not hit directly with another question. Be inventive. If he
asks "Have you ever documented an OOPS product before?" Ask back "What is it
about your product that you'd want me to document?" Volley, backhand. He
probably replies "Well, our users need to know how to use the product, so I
suppose that's what you'd be doing."

You: "So I'd be writing mostly for the end user?"

Him: "Right."

You: "Mostly user interface, then, I suppose?"

Him: "Correct."

You: "Can you give me a picture of your end users?"

Him: "Oh, clerks and other low-level data entry personnel."

You: "Do such users need or want to know about object-oriented concepts?"

Him: "Well, I guess they wouldn't."

You: "Then I'd avoid writing about them, in my view. Now, what can you tell
me about the product?"

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.simplywritten.com/simply

                  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-