Conference Report
STC Berkeley senior member Ron Rothbart shares his experience at
the recent WinWriters conference in Seattle.
Single-Sourcing and Online Help:
A Report from the WinWriters Conference
In February, I
joined about 420 other technical writers at the eleventh annual WinWriters
Online Help Conference in Seattle. This was my second WinWriters conference.
My last one was 1996 when Microsoft announced HTML Help.
A good number of the conference sessions were about single-sourcing and
related topics, and a good number of exhibitors touted their single-sourcing
capabilities. Three main approaches to single-sourcing were represented:
1) using XML, 2) using a conversion tool like WebWorks, and 3) database
publishing.
At least four sessions covered or touched on XML. Tony
Self presented a comprehensive introduction to The XML Revolution,
and I attended three other XML-related sessions of interest.
XML at Microsoft
XML came up tangentially in Cheryl Lockett Zubak's session, Microsoft
Help Update, when she told the audience that Microsoft is developing
its own internal XML-based content management system. The aim is to enable
content re-use at Microsoft. While she made it clear that this is for
internal use only, she speculated that it may influence the external help
platform that will accompany Microsoft's next operating system, due sometime
in the next 2-3 years. (This upcoming help system should not be confused
with Help 2.0, which Microsoft has decided not to release as a general
help platform.)
Zubak said that Microsoft is using a variant of DocBook as the DTD for its new XML-based system. This is interesting because some single-sourcing advocates have cast doubt on DocBook's suitability for online help. DocBook was designed before the big shift to online documentation, and it is sometimes seen as too book-oriented. A team at IBM has proposed a topic-oriented alternative called DITA, which it argues is more flexible. Since Microsoft tends to set the standard for much of the software industry, it is noteworthy that they have chosen DocBook.
Home Grown System
In A Case Study of XML Authoring, Christopher Green presented a
home grown, XML-based authoring system that he created with the help of
a couple of developers at the company where he works. Chris acknowledged
that when he started on the project, he knew almost nothing about XML.
In my view, this shows in the system that he created.
For example, although one of the most important features of XML is that it enables the separation of content from presentation, one of the elements in Chris' DTD is called popuptext. Rather than keeping his DTD presentation-neutral, he built in the assumption that definitions would be presented as popups.
This is not to belittle Chris' achievement. With few resources and little experience, he made a good first effort. But it does highlight for me the need to really know what you're doing if you're going to build something that realizes the potential of XML.
XML on the Cheap
While acknowledging that moving to an XML-based system requires a big
adjustment for writers and a major investment in retraining, Michael Smith,
in his "Introduction to DocBook XML," made a case for using
free or inexpensive tools. No need to use Arbortext or FrameMaker, he
argued. You can do it all with freeware and cheap software.
Michael has been involved with SGML and XML for many years, he is very knowledgeable about it, and, if the truth be told, he is a bit of a geek. He is on the Technical Committee that maintains DocBook, and his outlook is heavily influenced by the open source movement. Michael demonstrated how you can use free XSL stylesheets to generate MS HTML Help and PDF from XML source files-if you are comfortable with a command-line interface and enjoy figuring things out for yourself. (By contrast, you'd pay a hefty sum for Arbortext's GUI tools for generating HTML Help and PDF.)
Michael defended DocBook, saying it is flexible enough
for many uses, not just books. He sees the DITA DTD as "reinventing
the wheel" and feels it undermines DocBook's mission, which is to
be the standard for the whole software documentation community. For information
on Docbook and related software, there are online resources available
at nwalsh.com
and sourceforge.net.
Conversion Tools
Perhaps the most visible single-sourcing tool at the conference was Quadralay's
WebWorks Publisher.
There were two sessions on WebWorks, and Quadralay had an exhibitor's
booth as well. WebWorks enables generating various help formats from FrameMaker
files (and now also from MS Word files). The conversion process is easy
and repeatable once you develop and map appropriate FrameMaker and WebWorks
templates. But developing those templates can take time and require using
WebWorks' own macro language.
Sean Brierley, in his session, A Case Study in Single Sourcing Using FrameMaker and WebWorks Publisher, described a "workflow" that he developed at the company where he works. Interestingly, he did this without getting too embroiled in WebWorks macros. He communicated a good deal of enthusiasm about his workflow and argued that it increased productivity significantly. Similarly, David Knopf, who is closely associated with WebWorks (having himself written the documentation for version 7.0), presented Tips and Tricks that did not require anything too geeky (although I don't think he presented much that isn't already in the WebWorks documentation).
Although I appreciated these presenters' efforts to make WebWorks accessible, my own experience is that to make it do just what you want and really sing, you do need to struggle with those macros, not to speak of DHTML and JavaScript. In this endeavor, the WebWorks users group is invaluable.
Matthew Ellison gave a session on Single-Sourcing with RoboHelp X3. RoboHelp is more of an authoring tool than a conversion tool, and some technical communicators (for example, Knopf and Brierley) say it is not a true single-sourcing solution. Despite the fact that the latest version of RoboHelp supports conditional text, Ellison's presentation failed to convince me that it really supports single-sourcing well.
Database Publishing
Tony Self's Delivering Content from a Database was a good overview
of database concepts and how they apply to delivering online help from
a web server. Chunks of information can be stored in tables and then delivered
to multiple media and reassembled in different combinations dynamically.
What made this approach really come to life for me was seeing the spirited
representative from AuthorIT demo his product in the conference exhibition.
AuthorIT combines database publishing with built-in content management
at a relatively modest price. Although it has not been adopted in the
U.S. by nearly as many companies as RoboHelp or WebWorks, if the demo
is any indication, AuthorIT
has a promising future.
Used
with the permission of Ron Rothbart.
This article also appears in the online
newsletter of the STC Single-Sourcing SIG.
