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: common text in manuals--what's your process? From:"Tammy Lloyd" <tlloyd -at- xaware -dot- com> To:"TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com> Date:Fri, 30 Jul 2004 13:38:09 -0600
Hi, Lisa,
What you are describing is single-sourcing. That is exactly what myself and the other technical writer at XAware have been researching and implementing for the past year or more.
We maintain thousands of pages of documentation and JavaHelp with just two writers. We use a combination of FrameMaker and a new product Veredus, which is developed and distributed by Rascal Software.
After extensively using text insets (for content and graphics), variables, and conditionalized text we've pretty much reached the limits of FrameMaker (7.0). The following are some issues we are running across by using text insets.
- when you open a document, you can't spell-check across the document and in each of the text insets; I recommend adding text insets to a new book that is specifically for maintaining these files and doing searches/replaces and spell-checks across them.
- also, we can't figure out how to use a hyperlink in a text inset that references a specific section within the document it is being used....I suspect there's no solution for this when you are using the same text across multiple books
- finally, FrameMaker doesn't support variable overrides; by this I mean, when you create a PDF file from a .book you cannot set an existing variable value to something different for just that build; instead, you must manually import the new variable values into every file in which the variable is used.
After learning to single-source with FrameMaker, we found that our next issue was how to get the content out of FrameMaker to create a JavaHelp. Ideally, it would be a product that we could maintain all of our content in and use to output the content into anything we wanted (PDFs, JavaHelp, HTML Help, etc.). A dream product, right?
Well, then we discovered Veredus. As of yet, we have not yet moved all of our content to Veredus; what we do have stored there is wonderful though and allows us to output PDFs for one entire document (700+pp), then output that same content into JavaHelp. If you're interested in single-sourcing, I recommend looking into this product. It's very new so it still has some issues; however, the latest builds have been very exciting, including multiple build settings with variable override capability, more control over the content's formatting within the viewer and in the output, and text inset capabilities.
I just thought you might like to know that there are others looking into this too. I suspect we're a bit further ahead in this game. If you would like more information, please let me know. I believe my manager (Virginia O'Connor) has written some information up on this.
