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.
-----Original Message-----
From: Keith Hansen
Sent: Monday, October 03, 2011 9:43 AM
To: TECHWR-L -at- lists -dot- techwr-l -dot- com
Subject: Single sourcing, RoboHelp, and Frame: Newbie
>>
1. What are the advantages & disadvantages of single sourcing?
>>
My current place is the first place I have ever used single sourcing, and I can no longer imagine NOT using it. I've used it on several side projects I have done since I first started using it.
What we do:
All of our source files are in Framemaker. There are books with chapters, and each of those chapters is made of up some in-line text, and a lot of text insets of other Framemaker files. We have a lot of information that is shared between books (commonly single-source things are procedures, notes/cautions, reference tables, etc.). Those insets can even be made of more insets, etc. This means we can re-use a lot of content in different ways - for example, I can have something as a procedure in a chapter but then also pull just that procedure into a quick reference sheet with completely different formatting (the paragraph names need to match up, but the paragraph styles can be different, and the parent topic's settings are applied to all the insets that make up the Frame doc). If a lot of information gets reused in your docs, it really can be the way to go.
When it comes time to cut the line for documentation, we have a couple of plugins to archive the files to another network location, and then we convert all the insets to text and update/generate our books (including some imported into RoboHelp to create Help files), sort of like branching the code line to create a release. The actual working docs stay in the same location and keep changing, but we have a copy of what was released with any particular system release (and yes, sometimes you do end up having to then make changes in two places when changes are required after you've initially generated the books, but it's easy to manage). RoboHelp usually does not like Frame docs with text insets, hence the steps of archiving/converting everything to text. Even for the largest of our books (2500+ pages) on times with a heavy network load, a book can updated in about an hour.
There are some quirks in the process (like managing variables, making sure you have templates applied universally if you add/update a style) and recently we have had some quirks with things not auto-updating as they have in the past, but it's pretty manageable. And much less of a headache than not having single-sourcing.
Create and publish documentation through multiple channels with Doc-To-Help.
Choose your authoring formats and get any output you may need. Try
Doc-To-Help, now with MS SharePoint integration, free for 30-days. http://www.doctohelp.com
---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
