Message Reference Guide: a workflow

IBM DB2 Migration Toolkit online help

18 December 2006

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 an automated workflow.

Development adds and deletes messages in the message catalog. They initially write a long description directly in the catalog.

MTKInformix.messages

msg.15.category=20
msg.15.num=18
msg.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=false
msg.15.parm.count=1
msg.15.parm.0=<column name>

The documentation build script extracts the message catalogs, checks to see if there are new messages, and generates (1) a DITA library of short messages and (2) for new messages, generates DITA message topics that contain references to the short messages and the development-provided long descriptions. The writer then copyedits these new DITA message files and the corresponding short messages in the catalog, and checks them into source control.

msgph.dita

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE topic PUBLIC "-//IBM//DTD DITA IBM Topic//EN"
 "ibm-topic.dtd">
<topic id="msg" xml:lang="en-us">
<title>Message phrase library</title>
<body>
...
<p><ph id="sdMTKI0018"><xref href="../ref/errorwarn.dita" type="concept"
>Input Script Error</xref>: Possible ambiguous column reference: &lt;column name></ph></p>
...
</body></topic>

MTKI0016.dita

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE reference PUBLIC "-//IBM//DTD DITA IBM Reference//EN"
 "ibm-reference.dtd">
<reference id="MTKI0018" xml:lang="en-us">
<title>MTKI0018</title>
<shortdesc outputclass="msgph"><ph conref="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 <tm tmclass="ibm"
tmowner="IBM Corporation" tmtype="reg" trademark="DB2">DB2</tm> UDB.</section>
</refbody>
<related-links>
<link href="../infx/statements.dita" type="reference"></link>
</related-links>
</reference>