User manual and online help: single-sourcing in Word?

Subject: User manual and online help: single-sourcing in Word?
From: "Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Fri, 4 May 2001 11:09:36 -0400

Sarika reports: <<I have to implement Robo HTML Help in our Software. I want
to avoid duplicity of work. Although I know I can import a Word doc and
convert it into help file, but the problem is I don't need screens in Help
file which is otherwise included in the Manual. If I choose to remove the
screens, I will have to change the language flow of the entire Help File. Is
there any other way of managing both of them or what would be the ideal
thing to do in such a situation.>>

As you note, you should ideally not duplicate material in the online help
that appears in the manual, and not duplicate material in the manual that
appears in the online help. The reason for this is that online help and
printed manuals serve almost entirely different purposes: Use the printed
material for introductory material, context (e.g., descriptions of the
interface metaphor), tutorials, troubleshooting information (since you can't
troubleshoot via the online help if the software or help file won't work
properly), and so on. Use the online help to answer questions that the user
wants to answer immediately, while they're looking at a menu or dialog box.

More realistically, there is usually some overlap between the manual and
online help because some descriptions fall into both categories, but if you
make a clear distinction between the different roles of printed and online
documentation, you'll usually see that there's less need to make one file
serve two purposes than you at first believed*. Unless you're documenting a
really large product, it's probably unnecessary to invest in a complex and
expensive single-sourcing solution. I've successfully done what you ask by
creating two separate files (one for print and one for online), and simply
copying material from one to the other where this was necessary. After
copying the information, I then modified it as necessary (e.g., "see page
18" in the printed manual would become a link to the correct topic in the
online help).

* There are situations when the online and printed manuals must be nearly
identical, but they're relatively rare and should be rare.

--Geoff Hart, FERIC
580 boul. St-Jean, Pointe-Claire, Quebec H9R 3J9
geoff-h -at- mtl -dot- feric -dot- ca


*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems
Available now at or info -at- devahelp -dot- com

Sponsored by Information Mapping, Inc., a professional services firm
specializing in Knowledge Management and e-content solutions. See or 800-463-6627 for more about our solutions.

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 for more resources and info.

Previous by Author: Adobe's InDesign?
Next by Author: "..navigate down the path.."
Previous by Thread: RE: ERWin --> Word
Next by Thread: API documentation?

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

Sponsored Ads