RE: Documenting open source software in product?

["Ed Manley" <edmanley -at- bellsouth -dot- net>]

Ditto to the previous responses on this - but let me add something.

A previous employer used both a third-party (FaxMan) and an open-source
application (for FTP) embedded in our application.

In the case of the third-party app the provider company was dead and gone,
the software never to be updated. We continued to use it because it was an
integral and fundamental part of our app. We owned the right to use it, and
it worked for us, so why change it? However, we documented only that it was
there, and how to use our app, not the FaxMan (FAX Manager) app itself.

Again, with open-source stuff, we documented that we used it, and how to use
our product, but not their app. itself.

As others have mentioned, documenting someone else's product can be a
nightmare. We partnered with another company who used our app. for their
processing engine but who wrote their own GUI, meaning we had to open our
APIs for them to hook to. However, much of our logic was embedded in .dlls.
These folks had to document the entire software, so every time we made even
a slight change to our app. they had to re-write much of theirs. This calls
for a level of intense communication and collaboration not often found and
difficult to sustain.

BTW, in neither case did we give clients a choice - we offered to let them
hire us to make changes if they really really had to. This negated any need
for the client to understand the internals of any embedded software we might
use.

Try a similar strategy, wherein you mention that you use the software in
question, but at most provide a link to the app's vendor where the reader
can seek detail if required.

The obvious danger here is that the vendor (or open-source) will upgrade
their software to do tricks your embedded version won't do. Then the
pressure is on you to revamp your app. to play catch up, regardless of
whether those new features add value to your mission or not. Could be a case
here for not even mentioning that you use embedded software not of your own
design.

Hope that helps,
Ed



^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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

  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.

---
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.