Re: Documenting an OO application's user interface that exposes the OO stuff

Subject: Re: Documenting an OO application's user interface that exposes the OO stuff
From: Andrew Plato <intrepid_es -at- yahoo -dot- com>
To: techwr-l -at- lists -dot- raycomm -dot- com
Date: Wed, 1 Dec 1999 23:41:28 -0800 (PST)

> 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? If so, how did you describe
> objects, types, instances, etc. without also providing a crash course in OO
> concepts?

What is wrong with providing the reader a crash course in OO concepts? If your
readers need that knowledge to use the software more effectively, then teach
them. Better they learn it from you than some moronic trainer at Jim
McSucker's Training Emporium. At least you can steer them to the relevant
issues and control what information they learn.

I had a similar problem with this intrusion detection software I documented...

<plug> Which by the way the product just won the PC Magazine Technical
Excellence Award. It's called BlackICE from Network ICE and you need to buy it
right now so the company can hire me some more and pay me lots of money. You
can actually download my documentation from their web site - which I also
designed and coded. Tune in next week, when I'll bend space/time with a

Sorry, where were we? Oh yeah...

Most users of this product are not hardcore networking geeks. So I had to walk
the user through what the difference between high and low ports are, how
packets are routed, etc. In many ways, the majority of the document is a
highly specialized course in networking and hacking. Discussion of the actual
product comprised probably only 40% of the document.

> The problem is in coming up with terminology in the user guide that
> 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.

Why develop a new language? Use the standard OO terms and provide a detailed

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.

Andrew Plato

Do You Yahoo!?
Thousands of Stores. Millions of Products. All in one place.
Yahoo! Shopping:

Previous by Author: OT HTML
Next by Author: RE: ethical consulting practices?
Previous by Thread: Re: Future XMLers (was document management and xml)
Next by Thread: Re: Documenting an OO UI [long]

What this post helpful? Share it with friends and colleagues:

Sponsored Ads