RE: Documenting open source software in product?

[KMcLauchlan -at- chrysalis-its -dot- com]

> -----Original Message-----
> From: Bill Swallow [mailto:wswallow -at- nycap -dot- rr -dot- com]

> If it ain't yours, it ain't yours. Documenting someone else's product
> that is used in your product can lead to assumed 
> responsibility on your
> company's part to support that third-party software for your clients,
> which you don't want to have on your shoulders. Even though it's
> open-source, refer your users to that product's documentation.

I agree with Bill that, by writing your own 
documentation for Open Source third-party software 
that you include with your product, you are taking 
on a responsibility for something that somebody 
else will be changing, and that has pitfalls.

However, if the Open Source tools are really 
being included in your company's offering, 
then your company is controlling which VERSIONS 
are being used.  We all do similar stuff when 
we specify the package dependencies in software 
packages, so this is just another example of a 
dependency.  If the customer insists on having 
the latest and bleeding-edgiest of each package, 
when your product requires earlier, proven 
versions, then that's their problem.

For example, we sell product that requires only 
certain kernel versions of Linux or certain 
versions of Solaris and not others. If you want 
to try to force the issue, you don't get our 
support -- unless you are a huge potential 
customer and are working with us to qualify 
our product with the OS version that you use 
in your shops... but I digress.

You can include a proviso that you support version 
such-n-such, and if the customer prefers to use a 
newer/alternate version, then they must make-do 
with the documentation that comes with that other 
version.  Or they must deal with the areas where 
your document differs from the new OpenSource 
software.

There are arguments for both sides, and I agree 
with most of 'em. Just total up the benefits and 
the problems with each approach and make up your 
own mind. We're just here to suggest what some 
of the benefits and problems might be. You get to 
assign weight to them, according to your own 
situation.
 
> If you're including 3rd party software within your own and 
> shipping it,
> you generally have to first get rights to do so (not sure how 
> this works
> with open source apps though) and then usually you have the 
> app and docs
> for that product private-labeled for your company's use (that is, the
> product assumes your company's brand and not it's own). You 
> still don't
> support it 100%, but you do provide the documentation under your
> deliverable's "umbrella".

That works, only if the docs that come with the OpenSource 
stuff are sufficient to the task... where the task may be 
not only to get the customer going with the product, but 
also to present the proper, unified marketing image, etc.

/kevin

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  Your monthly sponsorship message here reaches more than
  5000 technical writers, providing 2,500,000+ monthly impressions.
  Contact Eric (ejray -at- raycomm -dot- com) for details and availability.
Save $600: Create great-looking Help files and software demos with
RoboHelp Deluxe. Get RoboHelp and RoboDemo - our new demo software - for one
low price. OR Save $100 on RoboHelp Office in June with our mail-in rebate.
Go to http://www.ehelp.com/techwr-l
---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -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.