single-sourcing and humble pie

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.



Follow-Ups:

Previous by Author: RE: What does $3 a page mean to you?
Next by Author: re: handshaking
Previous by Thread: Re: Re: Saving a FrameMaker book as a Word file
Next by Thread: RE: single-sourcing and humble pie


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


Sponsored Ads