arkadianriver

DITA content reuse

Sharing message source with documentation

18 Dec 2006

Roles
Information Architect, Technical Writer
Skills
DITA, Perl, JavaHelp, Reuse

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 "-//OASIS//DTD DITA Topic//EN"
     "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 "-//OASIS//DTD DITA Reference//EN"
     "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.