TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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
the
> 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
fart.</plug>
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
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.
Why develop a new language? Use the standard OO terms and provide a detailed
glossary.
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: http://shopping.yahoo.com
