RE: Good Manuals - Why Rare.

["Locke, David" <dlocke -at- bindview -dot- com>]

No, a product cannot be reverse engineered from the manual. In some cases
with best practice followers, a manual can be used as the acceptance test,
but this is rare. The best you can do from the interface is reverse engineer
the interface. The interface is not, however, the application.

The reason a product cannot be reverse engineered from its manual is that an
interface is a view of the underlying code or objects. An interface is not
the code or objects themselves. What this means is that the objects that are
visible from the interface are an abstraction of the objects in the
application. In our products, we use a database metaphor. That metaphor is
all over the interface. And, its the best way to think about what we do.
But, the underlying code uses one database for purposes unknown to the user.
And, in the user's data flows there are absolutely no databases. 

Just like a database view does not reflect the organization of the tables
themselves. A database view, instead, reflects the fields included in a
query, which may span tables. 

The user's conceptual model is a model of the application itself. It is a
model of what the user can see from the interface. Many objects and their
details cannot be seen from the interface. 

In addition, programmers have no expectation that they can reverse engineer
a product from a manual. Why? They have the tools to reverse engineer the
code, so why bother with the manual. And, if the application was created in
a collaborative prototyping environment, there will be some portion of the
application embedded in the code that is implicit and prelinguistic rather
than explicit. The only way to capture that is the reuse the code.

Market mechanics provide the thinking that companies use to justify bad
manuals. And, our one-manual-all-audience-at-all-times approach doesn't
expose the appropriate strategy choices to management. 

I've been idealistic enough to think that we fit into the post-sale
enactment chain. That's where my value add comes from. Experts developed
within careful limits usually champion the product underlying their
expertise. Experts are retained. Experts serve as the social reference that
the other users turn to, which in turn helps to retain the expert's company.

But, this model doesn't work, because this is the case only as long as the
company doesn't become a market leader. Blue-sky is a market leader. Their
manuals and treatment of customers is less than desired, because they don't
have to cater to our needs. Are we going to use someone else's tool. No. Of
course, not. They are the standard.

That is why documentation is poor in most cases. Standards matter. Manuals
do not. 

On top of that, the companies that do invest heavily into manuals do so to
create a market barrier. Most entrepreneurial startups don't have the money
or the will to match Novell's or Microsoft's documentation efforts. They
spend 20% of programmer effort just planning what contractors will produce.
Most startups focus on OPM, "other people's money", so they can only emulate
the obvious. They leave localization up to individual distributors. They
leave the documentation effort up to a few writers to follow the obvious
standards, and to do so with little if any management guidance or bandwidth.

I've worked with management that said that they sold training. They didn't
feel that documentation was worth the effort. And, in truth, they didn't
spend the effort on the training development either. Instructional design is
planning, and planning is bureaucratic. But, hey, the customers didn't buy
the product either.

There are perfectly good reasons for bad manuals. Some have no bearing on
the effort put forth by the documentation team members.

David W. Locke




-----Original Message-----
From: Chris Hamilton [mailto:cah_91 -at- yahoo -dot- com]
Sent: Thursday, March 16, 2000 7:50 AM
To: TECHWR-L
Subject: Re: Good Manuals - Why Rare.


>> Scottie Lover said:
 
...If you hand a good programmer a well-written user
guide [written by a competitor company],he can
probably use it to create a system which would
otherwise have taken years to put together.
 
Chris responds:
Do you really think so? I'm not being fecetious, but I
am struggling with this. 

Depending on the product, my assumption is that you
shouldn't innundate the reader with details about the
internals, except on a need-to-know basis. I need to
test that theory, it seems. From a business
standpoint, this seems like something you _wouldn't_
want to do. I guess my question is, _should_ we write
to enough detail to let someone reverse engineer the
product? My initial thought is that we shouldn't, but
I'm willing to be trained by people with more wisdom
and experience than I have.

__________________________________________________
Do You Yahoo!?
Talk to your friends online with Yahoo! Messenger.
http://im.yahoo.com

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Sponsored by Weisner Associates Inc., Online Information Services
Training & consulting for RoboHELP, Dreamweaver, HTML, and HTML-Based Help.
More info at http://www.weisner.com/train/ or mailto:training -at- weisner -dot- com -dot- 

Your web site in 32 languages? Maybe not now, but sooner than you think.
Contact ForeignExchange for the FREE paper, "3 steps to successful
translation management" (http://www.fxtrans.com/3steps.html?tw).

---
You are currently subscribed to techwr-l as: dlocke -at- BINDVIEW -dot- COM
To unsubscribe send a blank email to leave-techwr-l-10315J -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit 
http://www.raycomm.com/techwhirl/ for more resources and info.