TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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.
