Re: Good Manuals - Why Rare.

[Peter <pnewman1 -at- home -dot- com>]

Chris Hamilton wrote:
> 
> Peter--
> 
> I expect that we actually agree more than disagree. We
> both want to make life as easy as possible for users.
> It's just when we get down to the details that we
> disagree.

Agreed. The idea is to advise the user how the product is to be
used.     
 
>And I don't have to write
> very much about the internals to necessarily tell you
> how to use the product effectively.

Yes but I should know at least what they are. Then, a second level
manual for advanced users should be made available. Let's take MS Excel
as an example. There is very basic user information included in the help
file. Just enough to get started. Then, if I want to implement the
automation features, I have to dig deeper. (both into the subject and my
pockets.) At least I am made aware of the existence of the features.
Yes, I know about undocumented and unsupported features. A discussion of
that would constitute a book. 
I think most of us also agree that too much information may actually be
counterproductive to a beginning user. Of course, that decision depends
who the anticipated user is. I doubt that documentation for Cisco
routers would be, or should be intelligible to the average consumer.
OTOH, documentation for games is on a totally different level.

> 
> Let's use APIs as an example. Typically a product will
> have internal and external APIs. You seem to indicate
> that all of them should be documented. But you can't
> use the internal APIs; you don't have access to them
> or a conscious decision has been made by the company
> to keep them out of the documentation. 

But I should be given a clue as to what can be done with the product and
how to use it. If not, when that company want me to purchase v2.1, I may
go to a competitor who tells me about the feature that just happens to
be useful to me. It would be a shame for a company to lose a sale
because of a perceived lack of an important (to me,) feature. Although
that function may be present in the first product, if I don't know about
it, it doesn't exist. 
Perhaps my viewpoint comes from years of giving management advice that I
believe to be helpful in long range strategic planning. As is indicated
in many of my postings, I have an ingrained difficulty in just following
orders.  

> try to align myself with the user, I work for the
> company. They pay me. And part of what they pay me for
> is to not give away the company jewels. Now you're
> free to consider that arrogance on my behalf or the
> company's behalf, but that's the chance you take in
> making these decisions.

Its truly refreshing and commendable to see that you are one of those
rare people who are not not afraid to make and defend decisions. There
are many who are afraid to do so. 
 
> Intentional violations also subject the plaintiff to a
> costly legal fight with no promise of a payoff in the
> end. I expect that if I were to cause my company to
> have to litigate over such a thing, even if it won, I
> wouldn't be there at the victory party.

The decision as to what to include and exclude is clearly situational. 

-- 
Peter

Arguing with an engineer is like mud wrestling with a pig.
You soon realize they both enjoy it.