Woe be unto them that learn about single sourcing from Intercom

Subject: Woe be unto them that learn about single sourcing from Intercom
From: David Knopf <david -at- knopf -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Fri, 25 Jul 2003 09:35:32 -0700

The summer issue of Intercom features an article, "Do-it-Yourself Single Sourcing," that can only confuse those who want to understand how to employ best practices when implementing a workflow based on single sourcing. A better headline for the article would have been, "Single sourcing the Hard Way."

A quick summary for those who may not have read the article or may not be STC members. (If you read the article, you can skip this paragraph.) In the spring of last year, the author found out that the navigational controls (contents/index/search) in his Help system did not work in the latest versions of Netscape and Mozilla. Because his authoring tool, ForeHelp, was no longer on the market, a fix would not be forthcoming. Over the summer of 2002, the author migrated his existing content to Structured FrameMaker 7, enabling him to save content in XML format. The author's process now includes writing content in FrameMaker, exporting the FrameMaker files to XML, creating a shell Help project in ForeHelp, writing additional content in ForeHelp, and then running a set of perl scripts to extract content from the XML files, save the content in a set of HTML files, generate an index and related topics lists, convert the ForeHelp table of contents to JavaScript, import the extracted FrameMaker content and JavaScript into the HTML files, build a full-text search database, and copy various files to appropriate locations in the file system. The author states that three months of work were required to implement this system.

The process involves, in a nutshell, procedures written in FrameMaker, non-procedural Help topics written in ForeHelp, perl scripts to process XML files, a shareware/freeware tool called Foldertree to build a JavaScript-based table of contents, and a freeware utility called HyperInclude to enable "automatic" includes in HTML files. So, by my count, we have two content authoring tools (FrameMaker and ForeHelp), and three additional tools used to provide various services necessary to build the actual deliverable Help system (perl, Foldertree, and HyperInclude).

This may be an impressive technical accomplishment, it may have been fun and challenging to implement, and it may work very well for the author in his particular work environment. What it is not, is a sensible approach to implementing single sourcing in 2003. I have several questions and comments about the general suitability of the workflow described in the article.

Question 1: Is the workflow actually single sourcing?

I would say it is not. The author is extracting a limited amount of content (procedures only) from a set of FrameMaker files, importing that content into another tool (ForeHelp), writing additional content in ForeHelp, and performing extensive (automated) post-processing on the various files. The author may be saving time and achieving some efficiencies that were not possible using his previous workflow. However, with content authored in two different formats and two different authoring tools (FrameMaker/XML and ForeHelp/HTML), the workflow cannot accurately be described as single sourcing.)

Question 2: Is the workflow practical for the typical technical communicator?

How many Help authors, for example, want to use five separate tools in order to produce a Help system? How many technical communicators are proficient at writing perl scripts? (Don't everybody raise your hands all at once now.)

The author rejected off-the shelf solutions that are substantially easier to implement for technical reasons that are simply inaccurate. For example, the author considered WebWorks Publisher but rejected it because he did "not want to simply dump the manuals into HTML format" and because the "online Help projects are subsets of the information in a manual and they are formatted differently." There is absolutely no limitation in WebWorks Publisher that would prevent an author from producing online Help *directly* from a set of FrameMaker (or Word) files that is a subset of the information in the source files and is formatted differently. And the author could do so without resorting to a hodgepodge of perl scripts and shareware tools. In fact, these are precisely the issues that tools like WebWorks effectively solve. Implementing a solution based on WebWorks Publisher that would address the exact issues described in the article would likely have taken 70% less time than the author devoted to implementing the solution he describes.

Question 3: Is the workflow a good example of applying XML to technical communications?

Highly questionable. First, the author states that "I didn't have any immediate need for XML." While I certainly agree that XML offers many benefits, I generally don't recommend adopting it without a clear need and a convincing business case.

Further, the approach described in the article essentially uses XML as a bridge from one proprietary environment (FrameMaker) to another (ForeHelp). A more sensible approach would be to use XSL/XSLT to transform the XML produced by FrameMaker *directly* to the intended output format - in the author's case, cross-browser, HTML-based Help - thus removing legacy tools like ForeHelp from the equation altogether. True, XSL is not the easiest thing to learn, but then neither is perl. In addition, for authors who have an actual need to use an XML-based solution, there are increasing numbers of off-the-shelf solutions that can dramatically reduce the complexity and time required for implementation. Implementing a solution based on DocFrame, for example, to address the exact issues described in the article, would also likely have taken 70% less time than the author devoted to implementing the solution he describes.

It seems to me that articles like the one in Intercom - and this is the second or third misleading article on single sourcing to appear in Intercom in recent months - that create the mistaken impression that single sourcing is extremely difficult to implement. It is not. And it is getting easier all the time.

In conclusion, do-it-yourself single sourcing? Sure - if you have a legitimate need and can make a good business case. But whatever you do, don't emulate the process or workflow described in the Intercom article.

Required note: I am not a single sourcing zealot. I do not believe that single sourcing is the Holy Grail, nor do I believe it is the right solution for all projects. I do believe it is a highly effective workflow for some projects and some organizations and that using it effectively can improve quality and reduce costs.



David Knopf ~ Knopf Online ~ San Francisco
mailto:david -at- knopf -dot- com ~ http://www.knopf.com

Consulting & Training for Technical Communicators
FrameMaker ~ WebWorks ~ Structured Authoring ~ XML
WebWorks Publisher Certified ~ Adobe Certified Expert: FrameMaker
Member, JavaHelp 2.0 Expert Group
Moderator, HATT & wwp-users


sourcing tool for FrameMaker that lets you easily publish your content
online. No macro language required! http://www.ehelp.com/techwr-l3

Mercer University's online MS Program in Technical Communication Management:
Preparing leaders of tomorrow's technical communication organizations today.
See www.mercer.edu/mstco or write George Hayhoe at hayhoe_g -at- mercer -dot- edu -dot-
You are currently subscribed to techwr-l as:
archive -at- raycomm -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.


Previous by Author: Re: This file is protected...
Next by Author: RE: Keep Track of Experience
Previous by Thread: FrameMaker 7.0 Dictionary
Next by Thread: Re: Woe be unto them that learn about single sourcing from Intercom

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

Sponsored Ads