RE: Help without manuals

["Yigal Rahamim" <yigal -at- tds -dot- co -dot- il>]

Darren,

Thanks for pointing us to your interesting article.

As far as I understand the method you present allows you to convert a given
source in RoboHelp into printed documentation. However, the term
single-sourcing means that you maintain a single-source to create multiple
outputs. I assume that if there are changes in your Help file you will have
to repeat the entire process for each change or, simply make the changes
twice on each medium separately.

While researching single-sourcing I found two major approaches:

The "real" single-sourcing is a database driven solution which is mostly
based on XML. This approach does not allow "tweaking" of the output
deliverables (manual, help).

The other approach is very common I choose to call it "discount"
single-sourcing. This approach uses a combination of common authoring tools
like Word, RoboHelp, FrameMaker, ForeHelp, and WebWorks Publisher. While
thinking single-source you have first to define what information goes where.
Most methods I found start from the print version. Using FrameMaker features
like conditional text and variables you can define which information goes
where. For example you can define a condition called "HelpOnly" or
"PrintOnly". These conditions are maintained while importing into ForeHelp
and WebWorks publisher to create help files.
The new RoboHelp 2002 includes also an import feature of FrameMaker files
but, I am not sure the conditions are maintained and can be manipulated as
in ForeHelp and WebWorks. This method saved my clients time and money. You
can read the testimonials in our site www.tds.co.il/training4.htm#FH

Theoretically if there is a change in the content you type it only once in
FrameMaker, but in reality the FM file that are imported need some tweaking
so that's why I call it "discount" single-sourcing.

BTW conditional text can be also done in Word. If you know Word Macro
language and API you can do it with Word too and import the text to
RoboHelp.

If you plan to generate single source documentation and want both a manual
and online Help it would be better to move from print to online. Print
content should include more than online help.

I would be happy to read your comments.

Regards,

Yigal

_________________________________________
Yigal Rahamim
Documentation Consultant
Certified ForeHelp Trainer
TDS - Training & Documentation Solutions Ltd.
31 Lehi St, Bnei-Brak 51200 Israel
Tel: +972-3-5782818    Fax: +972-3-5782820
email: mailto:yigal -at- tds -dot- co -dot- il
Visit Our Web Site: http://www.tds.co.il/

 -----Original Message-----
From: 	Darren Barefoot [mailto:Darren -dot- Barefoot -at- capeclear -dot- com]
Sent:	Monday, November 05, 2001 1:36 PM
Subject:	RE: Help without manuals

Hi,

This is a pretty common issue on the list...you may want to check the
archives (I'm certain that I've raised it before, for example).

As for the specifics of your question, I think hardware is a different ball
of wax than software. If you're a user working with HW, you need to be able
to refer to something, and unless all users have Palm Pilots or eBooks,
they're going to need a manual.

As for software, the trend away from printed manuals has been going on for
several years. I'm just implementing such a strategy for the second time
(that is, I'd already done it at another company about 18 months ago). The
first time I did it we received a little grumbling from customers, but we
did deliver the docs in both help system and PDF format. The approach--the
one you mention about going from help to PDF--that my team took is described
in an article at
http://www.darrenbarefoot.com/writingsamples/SingleSourcing.pdf. This
approach was pretty onerous. We undertook this route because we had
abandoned updating our Frame files months earlier, so our help system was
our most up-to-date source. We then had a requirement for a PDF version, so
we had no choice but to go help-to-PDF.

Thanks. DB.

> -----Original Message-----
> From: Erika Yanovich [mailto:ERIKA_y -at- Rad -dot- co -dot- il]
> Sent: 05 November 2001 08:32
> To: TECHWR-L
> Subject: Help without manuals
>
>
> Dear collegues,
>
> Lately I see more and more companies (SW manufacturers) shipping their
> products with on-line help only and no manual. You cannot even order
> manuals separately, as they don't write/produce them anymore. Is this
> common practice? Can we also stop writing them (we manufacture mostly
> HW and some network management SW for the HW) without looking weird?
>
> Up to now we wrote manuals and then converted them to on-line help,
> but I noticed from past discussions on this list that some of you do
> it the other way around: write the help and convert it to manuals.
> What are the advantages of this approach? Is it possible to convert
> from webhelp to PDF?


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Be a published author!  iUniverse gives you: a high-quality paperback, a
custom cover design, and distribution to 25,00 retailers.  Join our almost
10,000 published authors today. http://www.iuniverse.com/media/techwr

  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.