Message Reference Guide: a workflow

Skills

DITA

Perl

JavaHelp

Message reference

Summary

Development and documentation organizations must work closely to ensure information
is both timely and accurate. Message information is a classic case of the kind of
information that grows quickly and requires a consistent and meticulous workflow.
Automation is the best way to ensure nothing falls through the cracks.

For the IBM DB2 Migration Toolkit, I created such a workflow with a little
Perl script and the content reference capability of DITA.

Development adds and deletes messages in the message catalog as they need them.
They initially write a long description directly in the catalog
(a Java properties file).

# ...
msg.15.category=20msg.15.num=18msg.15.short=Possible ambiguous column reference: {0}msg.15.long=This column occurs in more than one table in the from clause (or more \
than once as a column heading in the select list for an order by clause). The \
translation may cause an error in DB2 UDB. \
<p><a href="../Docs/instmts.html">More information</a>msg.15.warning=falsemsg.15.parm.count=1msg.15.parm.0=<column name># ...

In the documentation build, the Perl script extracts the message catalogs, checks to
see if there are new messages and generates the updated DITA library of short messages.

For new messages, it generates new DITA message topics that contain references to the
short messages and the development-provided long descriptions.

<?xml version="1.0" encoding="utf-8"?><!DOCTYPE reference PUBLIC "-//IBM//DTD DITA IBM Reference//EN"
"ibm-reference.dtd"><referenceid="MTKI0018"xml:lang="en-us"><title>MTKI0018</title><shortdescoutputclass="msgph"><phconref="msgph.dita#msg/sdMTKI0018"></ph></shortdesc><refbody><section><title>Description</title> Either this column occurs in more than one table
in the FROM clause, or it occurs more than once as a column heading in the SELECT list
of an ORDER BY clause. The translation might cause an error in <tmtmclass="ibm"tmowner="IBM Corporation"tmtype="reg"trademark="DB2">DB2</tm> UDB.</section></refbody><related-links><linkhref="../infx/statements.dita"type="reference"></link></related-links></reference>

The writer then copyedits these newly created DITA message files and the corresponding
short messages in the catalog and checks them all into source control.