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.
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.
NEED TO PUBLISH FRAMEMAKER CONTENT ONLINE? "Mustang" is a NEW single
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.
