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 a workflow with a little Perl script and the content reference capability of DITA.

  1. 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=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>
    # ...
    
  2. 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.

    <?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>
    

    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">
    <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>
    
  3. 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.