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