michael micheletti - wordfactory

One of my favorite development projects at WRQ was the WordFactory technical note publishing system. I designed and built this to help technical writers update hundreds of technical articles on the WRQ support website. I worked closely with the writers, and authored a few articles myself to get a better feel for the application. WordFactory has been well-maintained and is still in production use at WRQ.

Click on an image below to see a full-size version in a new window.

When I got together with the writers early on to talk about what they wanted, what everyone said was they wanted to write using Microsoft Word, but then be able to publish their documents on the web, as plain text, or whatever, and also build indexes and navigation and all from them. So I built a publishing framework around Word using Access and Visual Basic. Writers used styles to indicate indentation and formatting, and WordFactory would navigate through the document, creating HTML from it. This image shows the main WordFactory Document Screen, with the Title tab visible. Documents are the main content entity in WordFactory.

A writer creates a document via the WordFactory application, setting title, summary, date, author and publication details. WordFactory then creates the bones of a new Word document for the writer. The writer then adds details to the document, including relationships to other documents and indexes, images, code samples, lists. At any time, a writer can elect to view the document in one of the output formats. This image shows the Publication tab of the Document screen, which is used to note details about when and for whom this document may be published.

Once a document is written and reviewed, it is scheduled for production. The Job Jar handles details of a production run, producing all scheduled documents for batch upload. This image shows the Job Run tab, which was used to configure and launch a scheduled job run. The transmogrifier produced static documents using a common formatting template. It was very satisfying to create a transmogrifier. It's a bit tough to tell from the screenshots, but the WordFactory icon is an overturned cardboard box.

Finally, here is a busy shot showing most of the WordFactory screens all at the same time. The Schedule tab of the Job Jar screen is shown in the foreground.

<--in-house admin : top of page : technotes-->

WordFactory turned out as solid as it did because I was able to work right with the technical writers as a part of their team. I moved into their group and reported to their supervisor and took time out regularly to write and edit documents for publication. I spent most of my time coding, but felt confident that I was building the right application for them since I understood their business.

If you had to build this again, would you build it the same way?

Hmm, that's a toughie. I had a lot of trouble with the Word API when I was building WordFactory. Some things I wanted to do were simply not possible, and some simple things were made needlessly complex. Many calls in the Word API worked like they'd been lifted unchanged from Excel, where they probably worked better. But the writers wanted to work in Word, so I guess that would have to stay.

One thing that is more widespread and supported now than it was then is XML. I'd probably think about building the transmogrifier as an XML/XSLT transformation. That way I'd just need to get the Word doc into XML and then let something like the Xalan parser do an XSLT transform, like how the reports work at InstantService. I think it might be easier to build a new transmogrifier to do XML/XSLT now than it was back then to create the formatted HTML code version.

I'd probably still use VB to create the application proper, since it's so fast to work in and integration with applications like Word works fine; it wasn't VB's fault that Word had such awkward API calls. Even though I mostly live in the Java world now, it's not really made for integrating with Microsoft desktop applications, and VB is.

At the time, the writers didn't want to have an active system, where they published to a database that then generated completed documents on the fly. A few years ago, this was not as reliable and widespread as it is now, so we created static documents and these worked out well. I guess this would be an area where understanding the writers, their current needs and those of their customers would be important before making a decision to change things.

Did that sound a little bit waffly, or was it just me?

I'm sure it was just you.

WRQ is a software development and consulting firm with offices in Seattle, Singapore and Holland. Their best known product is the Reflection series of terminal emulators.