Re: Documenting an OO UI [long]

[Dan Brinegar <vr2link -at- vr2link -dot- com>]

Be gentle, I haven't posted at length in here for a while 8-)

At 3:41 PM -0500 12/1/99, cclunas -at- pria -dot- com wrote:
>Has anyone had experience documenting an object-oriented application that
>exposes the underlying objects, types, instances, etc. right in the user
>interface, and makes the user work with them?

Well, I've done subjects that, in their time, were equally hairy.

>If so, how did you describe the
>objects, types, instances, etc. without also providing a crash course in OO
>concepts?

I think you'll need to provide a crash course...  building a crash course
can be fun if the experience-levels of the two audiences aren't too far
apart.

Depending on the user-audience, you could accomplish this with
 * a tutorial,
 * a thorough glossary and brief-but-strict definitions of each
widget/concept as they appear in the docs, or
 * pitching an absolute fit about the atrociously bad application design
that forces parts-pickers, shipping clerks and dockworkers to delve into
the complex-and-potentially-dangerous realm of OO design to get their jobs
done.

The first two options assume that you have the time, knowledge and
resources available to do them... the third option involves just-guessing
at a worst-case-scenario: but I've been *there* two or three times too
often. ;-D

>
>I'm not talking about an API guide here; the application will have a separate
>API guide.

*Assuming* there's a legitimate reason for the application and docs to
address two different audiences at the same time... ;-D

You'll always need to include conceptual stuff for newbies.

Let's take, for example, the _1998 Java Developers Almanac_: 962 pages of
1900 classes and 21000 members of the Java 1.2 class libraries. The back
cover sez "no matter what level Java programmer you are, you will find this
book an invaluable tool for everday development."

Sitting my butt down with the almanac, Laura Lemays' _Teach Yourself..._
book,  and the latest copy of CodeWarrior's Integrated Development
Environment, I was utterly lost over a year after starting back in on
programming (converting COBOL Subjunctive Parable Routines into Recursive
Allegory Classes ;-)

I *think* I finally understand how to use the darn book, but for me to have
been able to use it at first, I'd have needed a crash course (at least) in
the conventions, concepts, and formats used in the almanac: to have made
the almanac useful to me the first time, it'd be at least 1900 pages long,
and rendered useless for the hard corps programmer already familiar with OO.

So, okay: every time this situation has come up for me before, the best
solution boils down to creating *two* seperate pubs for each audience,
and/or even a third tutorial-for-dummies -- hear me now and believe me
later -- if the experience-levels of the two audiences are too far apart,
then trying to do it all for two audiences in one pub becomes a size and
support trauma...

>> The problem is in coming up with terminology in the user guide that
>non-OO-aware
>> users can readily understand that won't conflict with strict OO terminology.
>> The application will have a wide range of users: some who know OO, some who
>> don't.

Use the correct terminology with a definition block and refer them to the
tutorial and  _The Handyperson's Great Big Book of Object Oriented
Programming_ if need be, and the API guide ...

At 11:41 PM -0800 12/1/99, Andrew Plato wrote:
>
>Why develop a new language?  Use the standard OO terms and provide a detailed
>glossary.
>

F'rinstance, Everytime a term/concept comes up in the text, put a marker in
and add it to a list of things-to-define: this helps you keep track of
everything, and allows you to build your glossary at the same time.

>Educate the user. If the user understands how and why things are the way they
>are - they can use the product more effectively and as such, make the product
>more valuable.

During some of my scandalous chats with actual *users* at one gig, I
learned that the modern crop of system operators the company was training
were reclassified electricians, and not the Post-Doctoral Plant Engineers
who used the original systems:  As long as Scotty stays on the Enterprise,
all ya need is a list of steps on a cheat-sheet. The pubs assumed that the
users would automatically *know* when and why they needed to do
something...  "Ya canna wait too long to lock down a warp-core breach" is
only ambiguous for one audience...

"It's time you learned, Lieutenant, *why* things work on a starship."

<ramble-ramble-ramble>

-------------------------------------------------------------
Dan Brinegar   Information Developer/Research Droid

  Making action figures and writing about them lately, 'cos
  agency muffins just freak when they see my cane and the
  year-long disability break on my resume 8-)

vr2link -at- vr2link -dot- com          CCDB Vr2Link
http://www.vr2link.com     Performance S u p p o r t Svcs.

And "Mixed Company" action-scale models coming soon