June 2003 Columns
Content Management Using AuthorIT | A Report from the WinWriters Conference | Using Screen Capture for Single Sourcing| STC @ 50: Single-Sourcing Topics at the Annual Conference
Currently, Ron is developing a WebWorks-based single-sourcing solution at Arxan Technologies in San Francisco, where he is Documentation Lead. Before that he worked on a WebWorks-based solution at Financial Engineering Associates in Berkeley and an XML-based solution at Documentum in Pleasanton. Ron can be reached at ron_rothbart@pacbell.net.
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 (see http://www-106.ibm.com/developerworks/xml/library/x-dita1/index.html). 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, see
http://nwalsh.com/docs/tutorials/winwriters2001/index.html and
http://sourceforge.net/projects/docbook.)
Conversion Tools
Perhaps the most visible single-sourcing tool at the conference was Quadralay’s WebWorks Publisher (www.webworks.com). There were two sessions on WebWorks. And Quadralay had an exhibitors 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 (http://groups.yahoo.com/group/WWP-users) 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 (see
http://www.ehelp.com/products/robohelp/whatsnew.asp), 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 re-assembled 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 exhibitors hall. 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 (www.author-it.com).
The opinions expressed by contributors to the Society for Technical Communication (STC) World Wide Web site are solely those of the individual writers and do not reflect the opinions of STC, the members of the STC administrative council, or STC World Wide Web volunteers.
Reference herein to any specific commercial firm, commercial product, process, or service by trade name, trademark, manufacturer, or otherwise, does not constitute or imply its endorsement, recommendation, or favoring by the Society for Technical Communication (STC).
