XML Architecture for Customized User Assistance

By Sarah O'Keefe, Scriptorium Publishing Services, Inc.

This document and its companion files demonstrate one solution for customized documentation

Introduction

Content reuse enables technical communicators to create multiple deliverables from a single set of source documents. A key component of reuse is identifying which information belongs in which deliverable. Some customization is feasible with build tags (RoboHelp), conditional text (FrameMaker), topic reuse (FrameMaker and AuthorIT), and similar features. These techniques work best for relatively simple customizations, such as the following:

• Baseline and superset—The baseline, or common, documentation is one deliverable. Subsequent deliverables are created by adding information to the baseline. For example, you can document the "light" version of a product as the baseline and add more details for the "professional" version.
• Customizations do not overlap—To create multiple deliverables, you add information to the baseline documentation set. The information added for each deliverable is unique. For example, when creating information for print and online delivery, you create baseline documentation, and then you add some information that's included only in the printed version and some other information that's included only in the online version.
• Topic assembly—You create individual chunks of information as stand-alone topics. To create a specific deliverable, you collect all of the relevant topics and wrap information around them. A printed book, for instance, contains topics grouped into chapters along with front and back matter. An online help system requires topics, a table of contents, an index, and perhaps a browse sequence. Each deliverable gets a different collection of topics, but some topics are reused in multiple deliverables.

You can reuse at the paragraph level rather than the topic level, but for simplicity, this article assumes you are only doing topic-level versioning.

Using attributes to label conditional information

Extensible Markup Language (XML) offers a new approach to reusing and versioning information. Instead of taking a document-centered approach (in which you label information based on whether it is included or excluded in a deliverable), XML uses a content-centered approach. When you define your content model in XML, you create metadata for certain elements. This metadata allows you to filter information and collect topics for a particular deliverable automatically. Instead of creating baseline and custom content, you create topics with and without attribute values. For instance, to accommodate the professional and light versions of a document, you create an attribute called software-level. By default, the software-level attribute has no value. Whenever you create a topic that is only for the professional level of the software, you set the attribute value to match:

<topic>this topic goes everywhere</topic>
<topic software-level="pro">this topic is extra information for the professional version</topic>

XSL for conditional processing

Once you have information stored in XML format with the attributes assigned, you need to process the XML files to filter the output. This article uses Extensible Stylesheet Language (XSL) transformations in the examples. XSL processes content by matching element and attribute values. For example, to process titles in a document and create HTML output with the <h1> tag, you create an <xsl:template> element, as shown here:

<xsl:template match="title">
<h1><xsl:apply-templates/></h1>
</xsl:template>

To process topics, you write a similar matching statement:

<xsl:template match="topic">
<xsl:apply-templates/>
</xsl:template>

The <xsl:apply-templates/> command instructs the XSL processor to look for elements inside the <topic> element and process them. To set up conditional processing, you create a template that matches specific attribute values. For example, to discard professional-level information, you look for topics with a software-level value of pro and discard them (by omitting the <xsl:apply-templates/> command):

<xsl:template match="topic[@software-level='pro'] ">
<!--Topics with the software-level set to pro are discarded-->
</xsl:template>
<xsl:template match="topic">
<!--All other topics are processed -->    <xsl:apply-templates>
</xsl:template>

For delivery of printed and online documentation, you can write two XSL transformations, one for each type of output. The online transformation would include the following:

<xsl:template match="topic[@output-type='print'] ">
<!--Topics with the output-type set to print are discarded -->
</xsl:template>
<xsl:template match="topic">
<!--All other topics are processed -->
   <xsl:apply-templates>
</xsl:template>

The print transformation would include the following:

<xsl:template match="topic[@output-type='online'] ">
<!--Topics with the output-type set to online are discarded -->
</xsl:template>
<xsl:template match="topic">
<!--All other topics are processed -->
   <xsl:apply-templates>
</xsl:template>

Notice that you do not have to explicitly process the topics where the output-type is set to the value you want to include. Those are caught by the general-purpose <xsl:template match="topic"> statement.

Instead of writing multiple stylesheets for each type of output, you can set the output you want as a parameter. You then test to see whether the value of the parameter ($output-type) equals the value of the output-type attribute (@output-type). The following code would output only those topics where the output-type attribute is set to print.

<xsl:param name="output-type">print</xsl:param>
<xsl:template match="topic">
   <xsl:if test="$output-type = @output-type">
       <xsl:apply-templates/>
   </xsl:if>
</xsl:template>

Versioning information by client

Your clients may dictate customization requirements. For example, some companies create customized software solutions for each client. There is baseline functionality, but features are added (or removed) for each client. The interface may change to accommodate each client's preferred look and feel. To provide user assistance for the first few clients, the low-tech "copy-the-old-version-and-make-changes" approach may be feasible, but as you add more and more variations, a better solution is needed.

The following table shows a simple list of client-specific features. Notice that in most cases, a particular feature is implemented for more than one customer.

XML's element and attribute organization provides an elegant solution to these customization challenges. You define a structure that accounts for all of the possible content variations, and then you use XSL transformations to extract what you need for each customer.

For instance, you create an attribute called client for the client-specific information. You assign the appropriate value or values to the client attribute as you create customized content. Another attribute would specify the version that the topic belongs in.

In documenting the features described in the preceding table, each XML topic specifies which clients use its content:

<topic client="barter,extreme">
<title>Setting up currency support</title>
<para>You can set up payments in US dollars or in euros.</para>
</topic>

The entire file is attached to this article: clients.xml

To process this file and produce client-specific information, you write an XSL transformation that outputs information based on the selected client.

<xsl:template match="topic">
<xsl:choose>
<xsl:when test="@client = 'all'">
<xsl:apply-templates/>
</xsl:when>
<xsl:when test="contains(@client,$client)">
<xsl:apply-templates/>
</xsl:when>
<xsl:otherwise></xsl:otherwise>
</xsl:choose>
</xsl:template>

See the demo: client_form.html. Note that this demo works only in Internet Explorer.

See the attached XML source file (clients.xml).

See the attached XSL source file (clients.xsl).

Processing complex versioning requirements

The examples provided so far call for versioning along a single axis; you create conditional information for different product levels, different platforms, or different clients. You can address these requirements with XML, but existing tools and unstructured documents also support this level of versioning.

As your reuse requirements get more complex, structured authoring and XML become necessary. Using XML, you can create information and publish it based on multiple condition axes. That is, you can publish information for different product levels, different platforms, and different clients out of a single set of source files.

This is a powerful concept, but it requires careful planning. First, you must develop a content model with metadata that accounts for the classifications that you need. The following table shows an example:

Using only four attributes, you set up a content model that allows for literally thousands of variations. Example topics would look like the following:

<topic software-level="pro" output-type="print" client="acme,citadel" platform="all">The platform attribute specifies that this topic applies to all of the different software platforms.</topic>
<topic platform="mac">This information will appear only in Mac-specific versions of the deliverables.</topic>
<topic output-type="online" platform="unix,win" client="citadel">This information appears only for UNIX and Windows versions of the online information for the Citadel client.</topic>

Setting up the attributes and developing the transformations could be challenging. The content creators, however, are presented with the most difficulty. For each topic they create, they must assign the correct attribute values. They must take into account the numerous different deliverables in which a topic could appear, and take pains to create content that works in many different contexts.

See the demo of versioning based on client and platform: client2_form.html. Note that this demo works only in Internet Explorer.

See the attached XML source file (clients2.xml).

See the attached XSL source file (clients2.xsl).

Conclusion

XML provides a deceptively simple framework for conditional information. You define attributes in the structure that provide metadata. When you publish from XML, you filter elements by specifying which attribute values you want in the output.

XML's content-centered approach allows you to support systems that are much more complex than what is feasible with version labels, such as build tags and conditional text tags.

Although XML can support versioning with extreme complexity, the same may not be true for content creators. Keep in mind that the authoring experience may become quite tedious if authors are constantly required to specify attribute values. You can mitigate this problem by providing common attribute values as defaults, and by requiring the bare minimum number of attributes necessary for your content.

A few notes about versioning in FrameMaker

FrameMaker's conditional text is extremely useful for versioning in one classification, but it quickly falls apart when you attempt to version across two classifications (for example, platform and client). Condition tags are always processed as a Boolean OR. For example, if two condition tags are assigned to a single piece of text, and one is set to show and the other to hide, the text is shown. This is usually not the behavior that you want. With attributes, you can process conditions as a Boolean AND. However, FrameMaker does not, by default, support showing and hiding information based on attribute values. To work around this problem, you have several choices:

• Use the Sourcerer plug-in, which allows you to show and hide information based on attribute values.
• Author in XML, and filter with XSL. Import the filtered information into FrameMaker for printing.
• Use FrameSLT to emulate XSL filtering in FrameMaker.
• Use FrameScript or the FrameMaker Developer's Kit (FDK) to extend FrameMaker to support attribute-based versioning.

Resources

FrameMaker FDK

partners.adobe.com/public/developer/framemaker/fdk/topic_7_1.html
Allows you to write C code to extend FrameMaker's base functionality.

FrameSLT

www.weststreetconsulting.com
An XSL emulator that runs inside FrameMaker.

Single sourcing

Single Sourcing: Building Modular Documentation, Kurt Ament, ISBN 0815514913

Managing Enterprise Content: A Unified Content Strategy, Ann Rockley, ISBN 0735713065

Sourcerer

www.advantica.biz/sourcerer

White papers

www.scriptorium.com/papers.html
Papers on XML, XML implementation, and more.

XSL Resources

XSL FAQ: www.dpawson.co.uk/xsl/index.html

xsl-list archives: www.biglist.com/lists/xsl-list/archives/

Jeni Tennison's resources: www.jenitennison.com/xslt/index.html

XSLT Programmer's Reference, Michael Kay, ISBN 1861005067

Mozilla JavaScript interface to XSLT: www.mozilla.org/projects/xslt/jsinterface.html

Special thanks to Char James-Tanny for answering some questions about AuthorIT.

Sarah O'Keefe is founder and president of Scriptorium Publishing Services, Inc. (www.scriptorium.com). The company provides technical publishing services with an emphasis on developing and deploying structured authoring environments. Sarah is an experienced trainer with Adobe Certified Expert (ACE) in FrameMaker and Certified Technical Trainer (CTT) credentials. Her background also includes technical writing, technical editing, production editing, and online help development. Sarah's publishing credits include FrameMaker 7: The Complete Reference, The WebWorks Publisher Cookbook, Technical Writing 101, FrameMaker for Dummies, and numerous white papers.