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:Re: Single Source: Yay, Nay, or TBD? From:Sean Hower <hokumhome -at- freehomepage -dot- com> To:"TECHWR-L" <techwr-l -at- lists -dot- techwr-l -dot- com> Date:Tue, 19 Oct 2004 08:11:09 -0700 (PDT)
-----------------------
Anne Allaire Burke wrote:
I feel that online documentation (Help, etc.) is used and learned
differently (from the user perspective) than it's hardcopy counterparts.
-----------------------
As others have pointed out, that's not single sourcing. A better example is a project I had put together with RoboHelp a little while back using build tags that defined whether a topic would be included in a specific chm. It worked beautifully because about 70% of the content was the same across all chm files. For the other 30% I just had to make sure the correct topics were assigned the correct build tags. That project generated eight different chms for eight different (but similar) products.
-----------------------
David Neeley reported:
A Web technology that illustrates the power of this kind of change is
www.csszengarden.com, which uses many different .css files to
transform the same HTML file so thoroughly that the result is quite
amazing.
-----------------------
That's a perfect example of single-sourcing in action! :-) I've been toying with the idea of doing the same kind of thing on my own Web site.
-----------------------
Bruce Byfield wrote:
I don't know what the original poster meant, but XML only takes care of
formatting. Structure and the length of paragraphs could still be a
problem.
-----------------------
Hmmm.......not really. Or more precisely, XML will take care of whatever it is you want it to take care of. Any one implementation of an XML application will only be as flexible as its design allows. If the XML doc is designed rigidly (ie for a very specific use) then your statement might be correct. But if it's designed to account for things like the structure and length of paragraphs, then these will not be an issue.
The bigger issue with single-sourcing is not necessarily the tool that you're using to do it. It's how you write your documentation. When I was single-sourcing those chm files, I had to be careful about product names (I avoided them) and other statements that would not apply to every chm that would include the topic. It took a little tinkering, and maybe a little more granularity than you would put into a non-single-sourced chm, but the end result was just as good and easier to maintain.
-----------------------
TechComm Dood wrote:
And to answer the burning question... no, XML is not always the best
solution.
-----------------------
Ding ding ding ding! He's completely correct. Here's a little article that I put together about this very issue...sort of: http://www.writethinking.net/index.php?p=31
-----------------------
Bruce Byfield followed up with:
For XML to be worth the time to set up, the material has to be extremely consistent in structure; it might work well in API documentation, for example. Without such consistency, you'd have to spend so much time designing that it would be counter-productive to consider using it in the first place.
-----------------------
But that can be said of _any_ single-sourcing effort, not just XML. The measure of any decision to single-source should be based on the amount of redundant (reused) information you have in multiple outputs. You might take the media into account too, but that may not be necessary depending on your needs/project/end-result/yada yada.
Bottom line is single-sourcing is a good idea when you have a lot of information that will be shared across multiple outputs. The between "not to single-source" and "to single-source" should be the line between "easy to maintain" and "I'm getting sick of writing the same thing over and over." :-)
ROBOHELP X5: Featuring Word 2003 support, Content Management, Multi-Author
support, PDF and XML support and much more!
TRY IT TODAY at http://www.macromedia.com/go/techwrl
WEBWORKS FINALDRAFT: New! Document review system for Word and FrameMaker
authors. Automatic browser-based drafts with unlimited reviewers. Full
online discussions -- no Web server needed! http://www.webworks.com/techwr-l
---
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- techwr-l -dot- com
Send administrative questions to lisa -at- techwr-l -dot- com -dot- Visit http://www.techwr-l.com/techwhirl/ for more resources and info.
