There’s more to XML for technical communication than just DITA.

Much of the industry chatter revolves around DITA content management, DITA tools, the vagaries of the DITA Open Toolkit, and DITA implementation hurdles. At Scriptorium, a steady (and large) percentage of our work is DITA-based. But there are lots of things you can do with non-DITA XML that are relevant to technical communication. This post describes a few creative solutions; perhaps they will help you think creatively about your options.

(All names and some project specifics changed.)

XML as a conversion tool

Our first customer (let’s call them the Allspice* Company) has a custom database, which the technical writers have no control over. The database contains information needed, in somewhat different form, for the user documentation. The documentation is currently in unstructured FrameMaker, and one of the chapters contains all of the database-derived information.

Here’s what we did:

• Allspice already has the ability to generate XML from the database.
• We took the generated XML and processed it with an XSLT transform to create XML that is FrameMaker-friendly. (For example, tables are set up as CALS tables in the processed content.) We also excluded some content in this step.
• In FrameMaker, we built a structured application that imports the custom XML and formats it to match the existing unstructured FrameMaker files.

Allspice can now export content from the database and bring it into FrameMaker as a fully formatted structured FrameMaker file. That structured file is then included in a book with the unstructured FrameMaker content. This process is completely automated and eliminates manual maintenance of the database-derived content in FrameMaker.

To me, this project was especially interesting because XML is just a convenient intermediate format. There’s no structured authoring involved.

XML as a publishing gateway

Another customer, Basil Corporation*, is using XML as a gateway to other formats. Once again, there is information in the organization that the technical writers must publish, but the writers do not control the source files for that information. In this case, Basil has XML files that use a custom structure. We preprocessed the files to (again) produce XML that is more usable from a content point of view. We then wrote (another) FrameMaker structured application for PDF output and a transformation that produces man pages (nroff files). Once again, there’s no actual XML-based authoring—just XML being used to extract the needed deliverables.

Custom XML for unique requirements

For a project for Cinnamon, Inc.*, we have topic-based content, which needs to be delivered in very simple HTML5. We ruled out DITA as a source format for a variety of reasons. The ones I can discuss are:

• The DITA content model is much more complex than what Cinnamon needs.
• The DITA Open Toolkit is much more complex than what Cinnamon needs.
• The various DITA CMSs are bigger than what Cinnamon wants (which eliminates one major advantage of DITA—the ready availability of CMS solutions).

Cinnamon needs to manage a lot of metadata, but the content itself is straightforward. Here, the solution will be a custom content model that provides what Cinnamon needs (and nothing else), along with an open-source tool stack. Yes, there will be a lot of custom programming, and I spent a good bit of time looking for a packaged (commercial or open-source) solution that meets Cinnamon’s requirements, but in the end, we realized that a bare-metal custom build was going to be the most efficient option given their requirements.

These three projects have something in common:

• The use of XML (and not DITA) to solve business problems related to technical communication
• Heavy reliance on custom programming
• Heavy reliance on open standards (particularly XSLT and Ant)

Is this a trend? I hope so, because these projects have been fascinating to implement.

What do you think?

* Not their real name.

We all know that Lorem Ipsum is not your friend. But sometimes, even sample content fails.

Recently, I needed to build a prototype HTML site design that included section navigation.

We built out a wireframe based on sample content provided by our customer. The whole thing worked fine, and they approved it, and off we went to implementation. During testing, we promptly discovered that our navigation wouldn’t work because we actually needed multilevel navigation in the left link list.

The moral of the story? Content drives requirements, and fake content gives you fake requirements.