- 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.
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> # ...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: <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>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.