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.
Subject:single-sourcing and humble pie From:lyndsey -dot- amott -at- docsymmetry -dot- com To:"TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com> Date:Wed, 14 Apr 2004 01:21:06 -0400
Timothy wants to know more about single sourcing. In my late posts on the
subject, I was (usually) vehemently against it, though occasionally I sat on
the fence or toppled to either side.
I have since started a job for a company that has a product that is marketed
to Canadian and US clients. Because of the different laws and processes in
these countries, the sw differs markedly in many aspects. Furthermore,
customers in both countries demand and get customizations to their versions
of the sw. For these reasons, if single-sourcing didn't exist, I would now
be ready to invent it. Without single sourcing, the number of people
required to customize the documentation and online help for every version of
the sw would make off-shoring a non-issue.
The method of ss that we currently use is basically a variation of
conditional text. Essentially the documentation contains generic texts
suitable for all readers, plus symbols that indicate where customized text
is to be pulled in at build time, plus symbols that indicate where text is
to be ripped out at build time. The difficulty for the TW is in reading and
updating the source text: the more customizations, the more symbols. In such
cases, if an error exists in the conditional text indicators, it can be
quite difficult to locate the problem.
In the situation described above, single-sourcing is the only sensible way
to proceed. But I think ss can short-change people. For example, creating
different output types--say online help and paper doc--from the same source
will only annoy the user. The online help for both FrameMaker and WebWorks,
for instance, contains exactly the same content as the user guide. I wasted
time looking for information in one after I couldn't find it in the other.
Had I known they were single-sourced, I wouldn't have bothered.
Other methods of single-sourcing exist. My employer's conditional-text
version is probably the simplest.
~~~~~~~~~~~~~~~~~~~~~
Lyndsey Amott
www.docsymmetry.com
Winnipeg, MB R3G 2J3
ROBOHELP X5 - ALL NEW VERSION!!
Have you tried the latest in Help Authoring from RoboHelp?
Try ROBOHELP X5 for Free - Now with Word 2003 support, Content
Management, Multi-Author support, PDF and XML support and much more!
Download a free trial today: http://www.ehelp.com/techwr-l4
---
You are currently subscribed to techwr-l as:
archiver -at- techwr-l -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.
