Re: Documenting products integrated with your own

[Philomena Hoopes <PHILA -at- MAIL -dot- VIPS -dot- COM>]

Anonymous User asked: How have you handled this type of
situation when dealing with third-party products that are integrated with
your product or that your product relies on?

Well...some years ago I was working for a company that contracted with a
number of vendors to manufacture large air pollution control systems
(precipitators and the like). Our manual provided information on the system
as a whole; if maintenance procedures, for example, were required for one of
the component products, our policy was to refer them to the manual for that
component. All of these manuals were provided in the product documentation
set, which could grow to monstrous size (up to 10 three-inch binders).

The downside of this was that our documentation for those components *was*
limited to what the manufacturers provided. If the 6' diameter exhaust fan
came with a single-sided information sheet that pictured the parts and gave
instructions on turning it off and on (and perhaps lubricating it)...well,
that was what the customer got.

I tried contacting some of the more cryptic vendors to request more complete
information. They generally responded that this was the documentation that
they'd been handing out since the product was invented back in Aught 6,
(exaggeration alarm beeping wildly here) and as the engineer who wrote it
was long since gone to a better...something...we just had to be content.

I won't go into the consequences of this. Let's just say that it's pretty
generally known that if such systems have a weak spot, it's statistically
likely to be in the documentation. And if an unscrupulous customer wishes to
avoid payment, noncompliance with the documentation specs can be a very
fruitful legal quibble. If I'm obsessive about paper trails now, this is
why.

I don't know if this helps, Anonymous -- I'd suggest that you document the
third-party products in the context of your system. If maintenance is
required for a module, say, that links your system to the third party
system, definitely document it. Cross-reference the documentation set as
much as you can. As I understand it, however, you're not responsible for
what Oracle, Microsoft, or whoever else does or doesn't document about their
own product.

Philomena Hoopes
Phila -at- vips -dot- com <mailto:Phila -at- vips -dot- com>
VIPS Healthcare Information Solutions, Inc.
(410) 832-8330 ext 845

 From ??? -at- ??? Sun Jan 00 00:00:00 0000=