Re: Documenting open source software in product?

Subject: Re: Documenting open source software in product?
From: Kevin McLauchlan <kmclauchlan -at- chrysalis-its -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Fri, 12 Jul 2002 09:28:41 -0400


We haven't yet, but it's in the discussion stages, here. So,
here's my thought:

IT DEPENDS ON YOUR SCHEDULE

To expand on that...

SOME Open Source software has pretty good documentation,
though most of that tends to be tools for programmers.

MUCH of Open Source software seems to have spotty, cursory
or downright missing documentation. Examples can be seen
when you click the "Help" button in many KDE applications...
and the Help opens to the uber KDE manual, because there IS
no actual help for the specific application.
Whoopee. You get to review the instructions for the KDE
interface one more time, but you don't get anything on what
the current program actually does, or how to make it
do it...

Several programs that I've been using recently -- including
OpenOffice stuff and K-Office stuff have a structure and
the introductory material, and a few important functions
documented, but other functions and topics are nothing more
than headings... place-holders for when somebody has the
time or when somebody figures out what that programmer
meant the function to do before he finally got hired away by
industry and abandoned the project... :-)

THEREFORE
I recommend that, if you have the time in your schedule,
you write the entire documentation for the product that your
customers will receive. If there's some existing Open Source
documentation for tools and components, then rework it
for consistency with your own document style, structure,
etc. If you rewrite it entirely, then it's yours. If you
just incorporate, then be sure to attribute.

When a customer buys an application, they want to be
told -- in one place -- all that they need to know, to use
the thing to best advantage. They really don't want to
begin setting up, only to find themselves being redirected
to dozens of documents, most of which are not included,
but live on the internet, many of which have radically
different styles and organization, and levels of
completeness.

On the other hand, if your schedule and budget are tight,
then whatever can be found on the web is better than
nothing at all. :-)

My two-bucks-worth.

/kevin

On Friday 12 July 2002 08:57, mary -dot- nurminen -at- nokia -dot- com wrote:
> I'm working on documenting a product which has a lot of
> open source software in it. How have you others handled
> this? Have you provided links to any possible
> documentation available in the web on that open source
> software? Or have you produced original material on the
> software in question?


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



References:
Documenting open source software in product?: From: mary.nurminen

Previous by Author: Osaka-ben
Next by Author: Re: Telecommuters: laptop or desktop?
Previous by Thread: Documenting open source software in product?
Next by Thread: RE: Documenting open source software in product?


What this post helpful? Share it with friends and colleagues:


Sponsored Ads