Tools
Editing In a Single Sourcing Environment
by Neil Perlin
Single sourcing is a hot topic that gets a lot of ink from authoring tool vendors. For the purposes of this column, I’ll define single sourcing to mean creating one set of source content and, using features like conditionality, variables, and snippets, output some or all of that content in a form customized for different audiences, display devices, formats, and so on. Nothing complex…
However, one of the things that’s interested me for the last few years has been the issue of editing in a single sourcing environment. If you’re a "real" editor, or an author who edits yourself, you know how hard it is to read the same content over and over while keeping both your eyesight and sanity. And that’s in a normal editing environment in which there’s one copy of the content.
Now consider a situation in which a doc group is single sourcing to output multiple versions of a software user’s guide. The content is largely the same, except that the product’s version number in one case is 4.1 and, in another, 4.2, and there are some differences in the content depending on the version. It’s easy to create such material by using features like conditionality and variables, but how do you stay focused in order to review and edit content that may be almost identical? I find this difficult to do.
Editors Explain Their Methods
To learn how "real" editors deal with this, I spoke with Meredith Kinder, manager of the STC’s Technical Editing SIG at the annual conference in Atlanta in May. I posed this question to her, which she sent out to the SIG membership:
"Assume that a project in a single sourcing environment contains a topic in which there's a paragraph that differs for each of two or more outputs, such as different clients. We can control these variations by either a) creating one paragraph or inserting variables to set up the variations, or b) creating a separate paragraph for each output and using conditions to determine which paragraph to use for a particular output. Now imagine this situation repeated for multiple topics. (There's nothing exotic about setting up a project like this, by the way.)
My question is whether any editors have really worked in a situation like this and how they would describe the experience. My issue is that the editor effectively has to review the same material over and over, each time looking for a small variation for the specific output, which has to be an incredibly tedious task and one that makes it difficult to maintain their concentration."
I got five responses to the post. Here’s what they had to say:
John J. Kuczynski, technical writer for Daimler Buses North America in Oriskany, NY, and a member of the Syracuse Chapter of STC writes:
"…while I don't use conditions myself, my predecessor did, so much, in fact, that I have a hard time keeping track of where those conditions are located in the document. I would have to agree with the statement that it gets to be very distracting when you're trying to edit the finished document before release."
David O'Brien, IPA Content Author for Red Hat Asia Pacific writes:
"I write all of the documentation for my project (5 manuals + release notes) using conditions in docbook xml. There are two primary conditions (enterprise and community) and on occasion one or more other conditions may be necessary (e.g., beta). To date, the use of conditions has not been so extensive as to create headaches, mainly because the edits are done on html on a single version, and are easily transposable to the other version. This may not always be the case, but so far we haven't run into any issues."
Gururaj B.S. writes:
"I guess it depends on whether you edit the source document (for example, FrameMaker because you mentioned conditional indicators), edit the document online (online review or some collaboration tool), or annotate a PDF.
If you edit a source file, the writer needs to provide instructions about showing or hiding the right condition indicators. If the same content with minor variations is used in multiple contexts (for instance, release notes for a product supported on multiple platforms), the writer needs to inform the editor that the same content repeats in paragraphs/sections X, Y, and Z.
Next option: Get one of your doc-production engineers or programmers to develop a simple macro using Perl, which offers many pattern-matching features. If you can save the Frame file as HTML or XML, you can pass this marked-up content as input to this macro or program, which can flag repetitive strings of text.
If you have some or little budget for software purchase, consider… tools like Compare PDF, which compares PDF documents and generates extensive reports highlighting the common information and similarities (including metadata). If you have a Frame source document with 3 conditional indicators, you can create three PDF files (show each condition and generate PDFs individually). Then you can compare the PDFs by using such comparison tools."
Alisha Sauer, Business Analyst I at SHAZAM, Inc., writes:
"I edit a single Framemaker document for 10 different types of clients using conditional text, basically your option B, inserting different paragraphs with the conditions. We output the training packets to PDF.
I am the only editor, and I have a group of trainers who are my subject matter experts and reviewers. It is a tedious process that takes days to complete a review for even the slightest edit, as the change will be in some of the training packets and not others, and review time is much longer for major revisions due to limited SME availability. So, making edits is not a simple process because the SMEs will come to me with something like, "in all training guides for debit card issuers, we need to add a new provision resulting from such project." I know which training packets include debit card issuers, so I can go in and give the new addition the conditions for that output. But the SMEs still have to review 10 multiple, lengthy training guides. We have begun saving edits and doing quarterly updates, so we're not constantly working on the training packets."
Mary B Burns, Documentation Editor for First Data, writes:
"We did something like b) below. We used FrameMaker conditions to create "A" and "B" versions of paragraphs and swap them out according to the final PDF output--20+ guides, some of them hundreds of pages, with traditional chapters.
The conditions were not easy to handle and added considerably to the items editors had to check for. For every output, you had to condition the original paragraph to hide appropriately (for A but not B, for B but not A, for both A and B), yet still display in the base version. There were frequently display issues (especially with Structured Framemaker): for example, a hard return would get lost when the conditions were turned on and off.
Once the versions were established, I didn't experience editing a high volume of repetitive text. Aside from spot checks of the conditional text display, for each release I only read text that was new or modified. The condition indicators (a different-colored font), plus the writer's change highlighting, narrowed the focus of what I had to edit. The A (regional) and B (product-oriented) changes to base text were typically not uniform, requiring that the modified paragraph and sometimes the surrounding text be considered new. It was really the time required to analyze how big a chunk needed conditionalizing, and the headaches conditions caused in production, that caused us to abandon this method and go to producing old-fashioned supplements to the base guide.
We used variables for company name and guide name in headers and footers, and probably could have used them more, but again, we didn't feel it justified the time for analysis."
Some Observations…
From this little sample, I can come up with three classes of responses:
- Companies whose single sourcing isn’t complex enough for this to be an issue.
- Companies whose single sourcing is complex enough for this to be an issue and who are dealing with it manually.
- Companies whose single sourcing is complex enough for this to be an issue and who are starting to deal with it using technology – homebrew utilities or features of commercial authoring tools.
These classes of responses follow the same trajectory as many prior documentation technologies, like online help authoring and web authoring. Each went from manual coding to coding using homebrew macros and utilities to coding using commercial software.
The small number of responses suggest that few companies are single sourcing at a level complex enough to make editing an issue, so far. But as companies enter new markets or broaden their product lines, and increase time-to-market and ROI throughout their operations, how will the authoring process, including editing, get faster, more flexible, more efficient, and more effective?
I expect that most of those improvements will come from technology, as has happened with many other tasks in technical communication. My question is how, and what can documentation groups do to prepare for this new use of technology?
I plan to use an expanded version of this column for my next Bleeding Edge column in the STC’s Intercom magazine so, if you’ve had to handle editing in a single sourcing environment, I’d like to hear from you.
And my thanks to my respondents from the Technical Editing SIG.
****************
is president of Hyper/Word Services (www.hyperword.com) of Tewksbury, MA. He has 30 years experience in technical communication, with 24 in training, consulting, and development for online formats and tools like WinHelp, HTML Help, JavaHelp, CE Help, RoboHelp, Flare, Mimic, Captivate, and others now known only in legend. Neil is a member of IEEE and STC, an associate fellow of the STC, and the founder and manager of the Beyond the Bleeding Edge stem that ran at the STC annual conference from 1999 to 2006.